[Zope3-checkins] CVS: Zope3/lib/python/Zope/App/Publisher/Browser - meta.zcml:1.8

Martijn Faassen m.faassen@vet.uu.nl
Wed, 4 Dec 2002 06:12:47 -0500


Update of /cvs-repository/Zope3/lib/python/Zope/App/Publisher/Browser
In directory cvs.zope.org:/tmp/cvs-serv25535

Modified Files:
	meta.zcml 
Log Message:
Added/modified documentation for various directives.  


=== Zope3/lib/python/Zope/App/Publisher/Browser/meta.zcml 1.7 => 1.8 ===
--- Zope3/lib/python/Zope/App/Publisher/Browser/meta.zcml:1.7	Fri Nov  8 14:56:31 2002
+++ Zope3/lib/python/Zope/App/Publisher/Browser/meta.zcml	Wed Dec  4 06:12:47 2002
@@ -7,74 +7,144 @@
         handler="Zope.App.Publisher.Browser.metaConfigure.view"
     >
       <attribute
-          name="factory"
-          description="a callable that realizes the view.  The View
-              factory interface is documented in IViewFactory.  View
-              factories are passed two arguments, the context object
-              and the request object." />
-      <attribute
-          name="name" />
+          name="name"
+          description="The name of the view. 
+ 
+              The name shows up in URLs/paths. For example 'foo' or 
+              'foo.html'. This attribute is required unless you use the
+              subdirective 'page' to create sub views. If you do not have
+              sub pages, it is common to use an extension for the view name 
+              such as '.html'. If you do have sub pages and you want to
+              provide a view name, you shouldn't use extensions." />
        <attribute
           name="for"
-          description="the interface this view applies to" />
-       <attribute
-          name="layer" />
-          <!-- "defaults to default" -->
+          description="The interface this view applies to. 
+
+              The view will be for all objects that implement this interface.
+              If 'for' is not supplied, the view applies to all objects 
+              (XXX this ought to change)." />
+      <attribute
+          name="factory"
+          description="A callable that realizes the view. 
+
+              The view factory interface is documented in IViewFactory. View
+              factories are passed two arguments, the context object
+              and the request object. You must specify either 'factory' or 
+              'template'. Attributes of the view can be exposed as pages 
+              with the 'page' subdirective." />
        <attribute
           name="template"
-          description="the name of a page template (must end in
-              extension .pt).  If you supply a template, you must
-              also supply a name." />
+          description="The name of a page template.
+
+              Refers to a file containing a page template (must end in
+              extension '.pt'). You must specify either 'template' or
+              'factory'. If you supply a template, you must
+              also supply a name. You cannot have sub pages if you
+              use 'template'." />
        <attribute
-          name="permission" />
+          name="permission" 
+          description="The permission needed to use the view. 
+
+              This attribute is required." />
        <attribute
-          name="allowed_interface" />
-          <!-- "must also supply a name or permission" -->
+          name="layer"
+          description="The layer the view is in. 
+
+              A skin is composed of layers. It is common to put skin specific
+              views in a layer named after the skin. If the 'layer' attribute
+              is not supplied, it defaults to 'default'." />
        <attribute
-          name="allowed_attributes" />
-          <!-- "must also supply a name or permission" -->
-       <subdirective name="page" 
-       >
+          name="allowed_interface"
+          description="Interface that is also allowed if user has permission.
+
+              By default, 'permission' only applies to viewing the view and 
+              any possible sub views. By specifying this attribute, you can
+              make the permission also apply to everything described in the 
+              supplied interface." />
+       <attribute
+          name="allowed_attributes"
+          description="View attributes that are also allowed if user has permission.
+
+              By default, 'permission' only applies to viewing the view and any
+              possible sub views. By specifying 'allowed_attributes', you can
+              make the permission also apply to the extra attributes on the 
+              view object." />
+       <subdirective name="page">
          <attribute
-             name="name" />
+             name="name" 
+             description="The name of a sub page of a view.
+
+             The name attribute is always required for the 'page' directive. 
+             It is common to use an extension for the name, such as '.html'." />
          <attribute
-             name="attribute" />
+             name="attribute"
+             description="The name of the view attribute implementing the page.
+
+             This refers to the attribute (method) on the view that is 
+             implementing a specific sub page." />
          <attribute
-             name="permission" />
+             name="permission"
+             description="The permission needed to use this page.
+ 
+             XXX Should we deprecate this? Could always be the same as
+             the main view." />
          <attribute
-             name="layer" />
+             name="layer" 
+             description="XXX deprecated" />
        </subdirective>
-       <subdirective name="defaultPage" 
-       >
+       <subdirective name="defaultPage">
          <attribute
-             name="name" />
+             name="name"
+             description="The name of the page that is the default.
+
+             The named page will be used as the default if no name is
+             specified explicitly in the path. If no defaultPage directive
+             is supplied, the default page will be the first page listed." />
          <attribute
-             name="attribute" />
+             name="attribute"
+             description="XXX deprecated" />
          <attribute
-             name="permission" />
+             name="permission"
+             description="XXX deprecated" />
        </subdirective>
     </directive>
 
     <directive 
        name="defaultView" 
-       handler="Zope.App.Publisher.Browser.metaConfigure.defaultView"
-    >
-      <attribute
-          name="factory" />
+       handler="Zope.App.Publisher.Browser.metaConfigure.defaultView">
       <attribute
-          name="name" />
+          name="name" 
+          description="The name of the view that should be the default.
+              
+              This name refers to another view that should be the
+              view used by default (if no view name is supplied
+              explicitly)." />
        <attribute
-          name="for" />
+          name="for"
+          description="The interface this view is the default for.
+
+              The view is the default view for the supplied interface." />
        <attribute
-          name="layer" />
+          name="layer"
+          description="The layer the named view is the default view.
+
+              The named view is only the default view in the supplied
+              layer" />
+      <attribute
+          name="factory"
+          description="XXX deprecated" />
        <attribute
-          name="template" />
+          name="template"
+          description="XXX deprecated" />
        <attribute
-          name="permission" />
+          name="permission"
+          description="XXX deprecated" />
        <attribute
-          name="allowed_interface" />
+          name="allowed_interface" 
+          description="XXX deprecated" />
        <attribute
-          name="allowed_attributes" />
+          name="allowed_attributes"
+          description="XXX deprecated" />
     </directive>
 
     <directive