[Zope3-dev] template 'usage' (was Zope 3 Newsletter 11)

[Garrett Smith]

I'm trying to get my head around the template 'usage' attribute -- I 
know it should be simple, but the 'ah ha' hasn't hit me yet.

It seems to me that 'usage' is just an abitrary way to configure a view 
with a particular piece of information in ZCML. This seems very useful, 
but why limit it to a single value among a predefined set?

I can imagine a host a number of view-related (or whatever-related) 
attributes being set via ZCML. E.g.

- a view/form caption
- whether or not a page section is visible
- a URL to redirect to after an action has occurred

Short of requiring developers to create their own ZCML directives, could 
we not handle these cases using an 'attributes' attribute, ala TALES? 
E.g. in the case of usage now, an 'attributes' tag would look like this:

  <view name="foo" class="Foo" permission="zope.View"
    attributes="usage objectview" />

I realize might be viewed as an erosion of well defined ZCML directives, 
but it looks to me this is what 'usage' is doing anyway. I think an 
'attributes' attribute would be far more useful.

  -- Garrett


> GODEFROID CHAPELLE: Page Template "usage" variable
> 
>   Usage in Page templates has been completed during the Rheinland
>   Sprint organized by DZUG.
> 
>   The following text explains the motivation and the use of the usage
>   variable. More information can be found in
>   app/browser/skins/README.TXT
> 
>   The Usage Variable
> 
>     A skin must manage structural elements like navigation, tabs,
>     location breadcrumbs... Skin pages need to show all or some of
>     those elements.
> 
>       o An object view (as in the Rotterdam skin) has a lot of those
>       structural elements.
> 
>       o In dialog-style pages, you don't want elements such as tabs,
>       menus, and the location bar.
> 
>       o For the screen used in adding a new item, you also want many
>       items to disappear, but also to add some information specific to
>       this screen.
> 
>       o In error dialogs, the location bar doesn't work, because
>       errors have no location.
> 
>     One option is to manage multiple versions of the master template
>     and applying them as whole-page macros on the various pages.  But
>     multiple master templates is cumbersome and error-prone.
> 
>     To solve this, the skin facility introduces a top-level TAL
>     variable called 'usage'. The usage variable is there to allow you
>     to maintain a unique template for a whole application. This
>     variable has a value that sets different modes of operation. By
>     testing usage, you can decide which blocks should be shown or
>     hidden when rendering the template.
> 
>     Having a unique template eases to enforce a coherent UI and
>     consistent look and feel by ensuring that structural elements do
>     not move too much on the screen.
> 
>     The main way to set the value of 'usage' for a page is through the
>     menu it is registered to. A menu is a set of conceptually related
>     links to pages. When you click on one of those links, you should
>     arrive to about the same type of UI with identical (or at least
>     similar) information available. Getting usage from the menu will
>     enforce (we hope) the coherence of the UI. Actually, if a page is
>     registered to a menu, its usage value gets set from the usage
>     value set on the menu through its ZCML directive.
> 
>     Anyway, usage can be overridden by initializing it through the
>     page configuration (ZCML directive).
> 
>     The values of the 'usage' are chosen to describe broad categories
>     rather than individual templates or elements.  These are the
>     proposed values:
> 
>       o 'usage/objectview' is the usage when browsing contents.
>       Example: folder contents.
> 
>       o 'usage/activitydialog' is the usage when you are modifying an
>       object in any way.  Example: rename.
> 
>       o 'usage/error' is self-explanatory.
> 
>       o 'usage/addingdialog' is used during the process of adding a
>       new item.
> 
>     Those values must be registered through the
>     <browser:usage name="usagevalue" /> ZCML directive.
> 
>     The following directives share the usage attribute :
> 
>      o browser:menu
> 
>      o browser:view
> 
>      o browser:pages
> 
>      o browser:page
> 
>      o browser:editform
> 
>      o browser:subeditform
> 
>      o browser:editwizard
> 
>      o browser:addform
> 
>      o browser:addwizard
> 
>      o browser:schemadisplay
> 
>     The usage attribute can only be set as one of the registered usage
>     values.
> 
>     As an example, the 'template.pt' master template in the
>     'rotterdam' skin has the following block::
> 
>       <div tal:condition="usage/objectview"
>            tal:repeat="structure view/tabs"></div>
> 
> CONTRIBUTING
> 
>   Please send Zope 3 news, and newsletter suggestions and requests, to
>   gary at zope.com, with "Zope 3 newsletter" somewhere in the subject
>   line. As you can see above, both quick and lengthy news items are
>   acceptable and desirable.
> 
> MORE INFORMATION ON ZOPE 3
> 
>   The central place to find Zope 3 information is currently
>   http://dev.zope.org/Zope3
> 
>   The Zope 3 mailing list is archived and managed at
>   http://lists.zope.org/mailman/listinfo/zope3-dev
> 
>   The Zope 3 development IRC channel, #zope3-dev at
>   irc.openprojects.net is (strictly) for discussion of Zope 3
>   development issues.
> 
>   Newsletters are (supposed to be) archived at
>   http://dev.zope.org/Zope3/Zope3Newsletter