[Checkins] SVN: Sandbox/ulif/zope.introspector/src/zope/introspector/viewinfo.txt Steal my own code.

[Uli Fouquet]

Log message for revision 87513:
  Steal my own code.

Changed:
  A   Sandbox/ulif/zope.introspector/src/zope/introspector/viewinfo.txt

-=-
Copied: Sandbox/ulif/zope.introspector/src/zope/introspector/viewinfo.txt (from rev 87512, grok/branches/ulif-viewinfo/src/grok/admin/viewinfo.txt)
===================================================================
--- Sandbox/ulif/zope.introspector/src/zope/introspector/viewinfo.txt	                        (rev 0)
+++ Sandbox/ulif/zope.introspector/src/zope/introspector/viewinfo.txt	2008-06-18 13:09:19 UTC (rev 87513)
@@ -0,0 +1,142 @@
+=====================================
+Determining views for context objects
+=====================================
+
+Let's start with a simple object:
+   
+   >>> class Mammoth(object):
+   ...     pass
+
+We define a view:
+
+   >>> import grok
+   >>> class MammothIndex(grok.View):
+   ...     pass
+
+We provide this view directly for our mammoth.
+
+   >>> from zope import component
+   >>> from zope.interface import Interface
+   >>> from zope.publisher.interfaces.browser import IBrowserRequest
+   >>> component.provideAdapter(MammothIndex, adapts=(Mammoth, IBrowserRequest),
+   ...                          provides=Interface, name=u'index')
+
+
+We create an instance of the mammoth:
+
+   >>> manfred = Mammoth()
+
+Using ``ViewInfo`` we can ask for all the views for our particular
+mammoth.
+
+   >>> from grok.admin.viewinfo import ViewInfo
+   >>> info = ViewInfo(manfred)
+   >>> list(info.getViews())
+   [(u'index', <class 'MammothIndex'>)]
+
+Let's create another view `simple` and register it for the base
+interface (``Interface``):
+
+   >>> class SimpleView(grok.View):
+   ...     pass
+
+   >>> component.provideAdapter(SimpleView, adapts=(Interface, 
+   ...                                              IBrowserRequest),
+   ...                          provides=Interface, name=u'simple')
+
+When we call ``getViews()`` again, it should return both views, since
+any object provides ``Interface`` (so our ``Mammoth`` instance should
+too):
+
+   >>> sorted(list(info.getViews()))
+   [(u'index', <class 'MammothIndex'>), (u'simple', <class 'SimpleView'>)]
+
+Because we really want to get all views for an object, we also want
+views defined in other layers, not only the default one. We define a
+layer:
+
+   >>> from zope.publisher.interfaces.browser import (IBrowserPage,
+   ...                                                IDefaultBrowserLayer)
+   >>> class ITestLayer(IDefaultBrowserLayer):
+   ...     pass
+
+and register SimpleView again for this layer::
+
+   >>> component.provideAdapter(SimpleView,
+   ...                          adapts=(Mammoth, ITestLayer),
+   ...                          provides=IBrowserPage,
+   ...                          name=u'simple2')
+
+When we check the views, it won't show up::
+
+   >>> sorted(list(info.getViews()))
+   [(u'index', <class 'MammothIndex'>), (u'simple', <class 'SimpleView'>)]
+
+Instead, we need to list the views for this layer in particular. Since
+we already have some views registered on the request, we get those as
+well, as these are registered for all layers::
+
+   >>> sorted(list(info.getViews(ITestLayer)))
+   [(u'index', <class 'MammothIndex'>), 
+    (u'simple', <class 'SimpleView'>), 
+    (u'simple2', <class 'SimpleView'>)]
+
+In order to get *all* views registered for an object, we first need to
+know which layers exist in the system. In order to get all the layers
+that are in use, we retrieve all registered skins.
+
+When we don't have any skins registered yet, we don't find any::
+
+   >>> from grok.admin.viewinfo import getSkins
+   >>> sorted(list(getSkins()))
+   []
+
+Let's create and grok a skin now::
+
+   >>> class OurSkin(grok.Skin):
+   ...    grok.name('ourskin')
+   ...    grok.layer(ITestLayer)
+
+To grok the skin, we first need to grok the skin grokker itself::
+
+   >>> from grok.meta import SkinGrokker
+   >>> grok.grok_component('SkinGrokker', SkinGrokker)
+   True
+
+Now we can actually grok the skin::
+
+   >>> grok.grok_component('OurSkin', OurSkin) 
+   True
+
+We should now see this skin::
+
+   >>> sorted(list(getSkins()))
+   [(u'ourskin', <InterfaceClass __builtin__.ITestLayer>)]
+
+We have a method ``getAllViews`` which gives the views registered on
+all skins for a particular context object (with possible
+duplicates). Besides those views defined on skins, we also return
+those views defined on IDefaultBrowserLayer::
+
+   >>> from pprint import pprint
+   >>> pprint(sorted(list(info.getAllViews())))
+   [(u'',
+     <InterfaceClass zope.publisher.interfaces.browser.IDefaultBrowserLayer>,
+     u'index',
+     <class 'MammothIndex'>),
+    (u'',
+     <InterfaceClass zope.publisher.interfaces.browser.IDefaultBrowserLayer>,
+     u'simple',
+     <class 'SimpleView'>),
+    (u'ourskin',
+     <InterfaceClass __builtin__.ITestLayer>,
+     u'index',
+     <class 'MammothIndex'>),
+    (u'ourskin',
+     <InterfaceClass __builtin__.ITestLayer>,
+     u'simple',
+     <class 'SimpleView'>),
+    (u'ourskin',
+     <InterfaceClass __builtin__.ITestLayer>,
+     u'simple2',
+     <class 'SimpleView'>)]