Current situation and problem

The browser:page directive does a lot. It can either take a class or a template or both to make a browser page. In either case it will create a new class that has the necessary interfaces and methods inplace. When using just a class, it can take an attribute other than __call__ to publish.

Why is this a problem? Because certain behaviour is mixed into the class created on-the-fly. This behaviour is not apparent in our view class, yet we assume it exists. It's magic and it's hard to understand what's going on:

• Page classes don't need an __init__ or anything like that, it's received magically.

• Page classes don't need to bear any notion that they are going to be publishable. This has led to the lack of understanding (among core developers!) what the difference between a mere browser view and a browser page is. (This is probably the best "proof" that the current system is confusing and lacks clarity.)

• The resulting class doesn't exist anywhere (because it's dynamically created). This makes debugging very hard:

  $ bin/zopectl debug
  >>> from zope.publisher.browser import TestRequest
  >>> request = TestRequest()
  >>> root
  <zope.app.folder.folder.Folder object at 0x2bfb330>
  
  >>> from zope.component import getMultiAdapter
  >>> getMultiAdapter((root, request), name=u'contents.html')
  <zope.app.publisher.browser.viewmeta.Contents object at 0x2084e10>
  

  This Contents class doesn't exist where it's mentioned. Finding the class that belongs to this view has become very hard now and not obvious to users that don't know about the magical class creation

Goals

• Be more explicit (or, perhaps "declarative" is a better word?) when creating browser pages (especially in Python).
• Browser "pages" are essentially just adapters to the Component Architecture. Implementation details (template or not, etc.) should not be of much interest during the registration.
• The browser:page ZCML directive handler currently perform a lot of automation (stuff you could also call magic, such as the class creation). Automation should better be done in Python, using convenient baseclasses (but not requiring them).

Use cases

1. A single template is registered as a browser page for an interface or class.
2. A class is registered as a browser page. It might or might not use a template for rendering.
3. Several browser pages from one class, possibly also involving templates, are registered.

Proposal

It is proposed to introduce the following three new directives of the http://namespaces.zope.org/browser2 namespace in Zope 3.3 to fit each use case above:

1. The <browser2:pageTemplate /> directive is introduced and will satisfy the use case of registering a single template as a browser page, without having to go through Python. This directive won't accept a class argument.

   Example:

   <browser2:pageTemplate
       for=".interfaces.IPhoenixFoundation"
       name="macgyver.html"
       template="macgyver.pt"
       permission="zope.View"
       />
   

   While this does do automation in ZCML (it creates a class on-the-fly), it is a compromise towards those people who think that browser page definitions in Python are dead chickens.

2. The <browser2:page /> will succeed the <browser:page /> directive. However, it will bear the following differences:

   • It can only register class or other browser page factories through the factory argument (which replaces the class argument and is in conformance with the <adapter /> and <view /> directives). These classes/factories need to implement IBrowserPage? (new in jim-adapter branch, formerly formlib's IPage?).
   • It will under no circumstance create new classes.
   • It will neither accept a template nor an attribute argument (the published attribute is always __call__). It will also not accept allowed_attributes or allowed_interface arguments (the allowed interface is assumed to be IBrowserPage?).

   In practice, this means that such classes can make use of the zope.publisher.browser.BrowserPage? base class (new in jim-adapter branch, formerly zope.formlib.Page) and only need to implement the __call__ method. If they want to use a template that does the HTML rendering, they can use ViewPageTemplateFile? explicitly (or namedtemplate, if they want to).

   Example:

   from zope.publisher.browser import BrowserPage
   from zope.app.pagetemplate import ViewPageTemplateFile
   
   class MacGyverPage(BrowserPage):
       __call__ = ViewPageTemplateFile(macgyver.pt)
       def someAuxiliaryMethodForTheTemplate(self):
           pass
   

   Since this class (and not some dynamically created subclass) is directly registered as an adapter, examples at the interpreter prompt will reveal this class as well:

   >>> zope.component.getMultiAdapter((phoenix, request), macgyver.html)
   <MacGyverPage instance at 0xeatmyshorts>
   

   Example of the registration:

   <browser2:page
       for=".interfaces.IPhoenixFoundation"
       name="macgyver.html"
       factory=".browser.MacGyverPage"
       permission="zope.View"
       />
   

   Note that this is just syntactic sugar for the following (it saves the type and provides parameters):

   <view
       for=".interfaces.IPhoenixFoundation"
       type="zope.publisher.browser.interfaces.IDefaultBrowserLayer"
       provides="zope.publisher.browser.interfaces.IBrowserPage"
       name="macgyver.html"
       factory=".browser.MacGyverPage"
       permission="zope.View"
       />
   

   or even:

   <adapter
       for=".interfaces.IPhoenixFoundation
            zope.publisher.browser.interfaces.IDefaultBrowserLayer"
       provides="zope.publisher.browser.interfaces.IBrowserPage"
       name="macgyver.html"
       factory=".browser.MacGyverPage"
       permission="zope.View"
       />
   

3. <browser2:pagesFromClass> serves the third use case and succeeds the <browser:pages> directive. It can be used to create multiple pages from one class. Each page created is a callable attribute of the class (e.g. a method).

   <browser2:pagesFromClass> will still have to resort to subclass creation, but it will not dynamically bind templates. In other words, the <page /> subdirectives will only take attribute arguments, not template arguments. Furthermore, these subdirectives will also be changed to take a permission argument so that different pages.

   Example:

   from zope.publisher.browser import BrowserView
   from zope.app.pagetemplate import ViewPageTemplateFile
   
   
   class PhoenixPages(BrowserView):
       macgyver = ViewPageTemplateFile(macgyver.pt)
       def someAuxiliaryMethodForTheTemplate(self):
           pass
       def update(self, data):
           pass
   

   Notice that the class here doesn't need to implement IBrowserPublisher?. Therefore, it is enough to inherit from BrowserView? (it would even be ok to inherit from nothing)

   Example of the registration:

   <browser2:pagesFromClass
       for=".interfaces.IPhoenixFoundation"
       class=".browser.PhoenixPages">
     <page
         name="macgyver.html"
         attribute="macgyver"
         permission="zope.View"
         />
     <page
         name="update.html"
         attribute="update"
         permission="zope.ManageContent"
         />
    </browser2:pagesFromClass>
   

Risks

• We're introducing new ZCML directives which in a way is contradictory to ReducingTheAmountOfZCMLDirectives [2]?. However, the directives we're creating will each serve a very specific purpose, unlike the existing <browser:page /> directive. <browsers:page />, <browsers:pageTemplate />, and <browsers:pagesFromClass> will do one thing and one thing only. That might not reduce the amount of ZCML directives but it hopefully reduces the amount of magic.
• APIDoc? does lots of funky inspection that relies on certain naming schemes. I've seen code in some APIDoc?-unrelated areas of Zope that have comments like # make APIDoc? work. I'm not sure how APIDoc? would work with the new set of directives.

Implementation status

This proposal has been implemented in the zope.browserzcml2 package (see http://svn.zope.org/zope.browserzcml2/). A version for Zope 3.2 and one for Zope 3.3 (based on jim-adapter branch) exist.

References

[1]? "ZCML needs to do less": blog entry, origin of some of the ideas mentioned above.

http://www.z3lab.org/sections/blogs/philipp-weitershausen/2005_12_14_zcml-needs-to-do-less

[2]? "Reducing the amount of ZCML directives": Proposal on the removal of ZCML directives that are either obsolete or introduce too much indirection. This proposal was largely influenced by [1]?, just like the ideas above.

http://dev.zope.org/Zope3/ReducingTheAmountOfZCMLDirectives

[3]? "Simplify skinning": Proposal regarding the consolidation of the layer and skin concept.

http://dev.zope.org/Zope3/SimplifySkinning

[4]? "Brainstorming about browser pages": Mailinglist thread announcing a predecessor of this document.

http://mail.zope.org/pipermail/zope3-dev/2006-February/018255.html

[5]? "RFC: The browser:page compromise": Mailinglist thread discussing this proposal:

http://mail.zope.org/pipermail/zope3-dev/2006-April/019162.html

Changes in version 3

• Propose to create new directives instead of changing the old ones and removed one risk in the process.
• Rename <browser:pages /> to <browser2:pagesFromClass />.
• Added a detailed list of "end-user" problems with the classic set of page directives.
• Mention implementation status and add a link to mailinglist thread.

Changes in version 2

• Identified another risk regarding APIDoc?.