[Zope3-dev] Mini proposal: simpify presentation-lookup api

[Jim Fulton]

Now we have:


     def getView(object, name, request, context=None,
                 providing=Interface):
         """Get a named view for a given object.

         The request must implement IPresentationRequest: it provides
         the view type and the skin name.  The nearest one to the
         object is found. If a matching view cannot be found, raises
         ComponentLookupError.

         If context is not specified, attempts to use
         object to specify a context.
         """

     def queryView(object, name, request,
                   default=None, context=None, providing=Interface):
         """Look for a named view for a given object.

         The request must implement IPresentationRequest: it provides
         the view type and the skin name.  The nearest one to the
         object is found.  If a matching view cannot be found, returns
         default.

         If context is not specified, attempts to use object to specify
         a context.
         """

     def getMultiView(objects, request, providing=Interface, name='',
                      context=None):
         """Look for a multi-view for given objects

         The request must implement IPresentationRequest: it provides
         the view type and the skin name.  The nearest one to the
         object is found.  If a matching view cannot be found, raises
         ComponentLookupError.

         If context is not specified, attempts to use the first object
         to specify a context.
         """

     def queryMultiView(objects, request, providing=Interface, name='',
                        default=None, context=None):
         """Look for a multi-view for given objects

         The request must implement IPresentationRequest: it provides
         the view type and the skin name.  The nearest one to the
         object is found.  If a matching view cannot be found, returns
         default.

         If context is not specified, attempts to use the first object
         to specify a context.
         """

     def getViewProviding(object, providing, request, context=None):
         """Look for a view based on the interface it provides.

         A call to this method is equivalent to:

             getView(object, '', request, context, providing)
         """

     def queryViewProviding(object, providing, request,
                            default=None, context=None):
         """Look for a view that provides the specified interface.

         A call to this method is equivalent to:

             queryView(object, '', request, default, context, providing)
         """

     def getResource(wrapped_object, name, request, providing=Interface):
         """Get a named resource for a given request

         The request must implement IPresentationRequest.

         The object provides a place to look for placeful resources.

         A ComponentLookupError will be raised if the component can't
         be found.
         """

     def queryResource(wrapped_object, name, request,
                       default=None, providing=Interface):
         """Get a named resource for a given request

         The request must implement IPresentationRequest.

         The object provides a place to look for placeful resources.

         If the component can't be found, the default is returned.
         """

I propose to replace these with:

     def queryPresenter(objectsandrequest, interface, name='',
                        default=None, context=None):
         """Query a presentation for the objects and request

         A components is returned that provides the given interface for
         the given objects and request. The objects and request are
         provides as a tuple. The request must be the last item in the
         tuple.  Zero or more non-request objects may be provided.
         A name may be provided to quality the presentation.

         If a presentation can't be found, the default is returned.

         A context may be provided to control where components are looked up.
         """

     def getPresenter(objectsandrequest, interface, name='',
                      default=None, context=None):
         """Get a presentation for the objects and request

         A components is returned that provides the given interface for
         the given objects and request. The objects and request are
         provides as a tuple. The request must be the last item in the
         tuple.  Zero or more non-request objects may be provided.
         A name may be provided to quality the presentation.

         If a presentation can't be found, a ComponentLookupError is raised.

         A context may be provided to control where components are looked up.
         """

Really, this just portreys presentation components as what they are: adapters
from zero or more objects and a request to some interface. It also makes the desired
interface required and more explicit.

So, for example, a call like:

   view = zapi.getView(ob, name, request)

will become:

   view = zapi.getPresenter((ob, request), someinterface, name)

where often, name will be '' and can be ommitted:

   view = zapi.getPresenter((ob, request), someinterface)

Jim












-- 
Jim Fulton           mailto:jim at zope.com       Python Powered!
CTO                  (540) 361-1714            http://www.python.org
Zope Corporation     http://www.zope.com       http://www.zope.org