[Zope3-checkins] CVS: Zope3/doc/zcml/namespaces.zope.org/browser - addform.stx:1.1 addview.stx:1.1 editform.stx:1.1 i18n-resource.stx:1.1 icon.stx:1.1 menu.stx:1.1 menuItem.stx:1.1 menuItems.stx:1.1 pages.stx:1.1 subeditform.stx:1.1 defaultView.stx:1.3 page.stx:1.3 resource.stx:1.3 skin.stx:1.3 view.stx:1.6

Jim Fulton jim@zope.com
Tue, 31 Dec 2002 13:27:20 -0500


Update of /cvs-repository/Zope3/doc/zcml/namespaces.zope.org/browser
In directory cvs.zope.org:/tmp/cvs-serv1916/doc/zcml/namespaces.zope.org/browser

Modified Files:
	defaultView.stx page.stx resource.stx skin.stx view.stx 
Added Files:
	addform.stx addview.stx editform.stx i18n-resource.stx 
	icon.stx menu.stx menuItem.stx menuItems.stx pages.stx 
	subeditform.stx 
Log Message:
Hold on to your butts! :)

In an effort to make zcml view definitions even easier to understand
(see 
http://dev.zope.org/Wikis/DevSite/Projects/ComponentArchitecture/ZCMLBrowserViewDirectiveSimplification
)

I've finished a long-overdue refactoring of the configuration
directives for defining views. The logic is now a good bit less
complicated. 

I also simplified the way security assertions on views were
handled. To make this work right, I had to fix a bug in the
publication machinery. Now, as objects are traversed, the results of
traversal are put in security proxies.  This is really necessary to
treat URLs as "untrusted code", which they are.

I updated the meta-configuration directives for views and ran the zcml
documentation utility, so there is now documentation for the (new)
view directives. See the files 'page', 'pages', and 'view', in 
'doc/zcml/namespaces.zope.org/browser'.

I feel these changes are highly desireable for the alpha, but they are
significant enough that the chance of breakage is a lot higher than
I'd like just before the alpha.  I'd appreciate it if folks would let
me know if I've broken anything.



=== Added File Zope3/doc/zcml/namespaces.zope.org/browser/addform.stx ===
addform (function zope.app.browser.form.add)

  Attributes



=== Added File Zope3/doc/zcml/namespaces.zope.org/browser/addview.stx ===
addview (function addview)

  The addview directive defines an add view that has subpages.
  
  An add view is a view for a specific adding interface,
  IAdding. This directive is a convenience directive that allows
  the for interface to be ommitted, since it is implied.
  
  The pages provided by the defined view are accessed by first
  traversing to the view name and then traversing to the page
  name.

  Attributes

    layer -- (optional) 

      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'.

    title -- (optional) 

      The browser menu label for the page (view)
      
      This attribute must be supplied if a menu attribute is
      supplied.

    name -- (required) 

      The name of the view.
      
      The name shows up in URLs/paths. For example 'foo'.

    for -- (required) 

      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).

    permission -- (required) 

      The permission needed to use the view.

    allowed_attributes -- (optional) 

      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.

    allowed_interface -- (optional) 

      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.
      
      Multiple interfaces can be provided, separated by whitespace.

    menu -- (optional) 

      The browser menu to include the page (view) in.
      
      Many views are included in menus. It's convenient to name
      the menu in the page directive, rather than having to give a
      separate menuItem directive.

    class -- (optional) 

      A class that provides attributes used by the view.

  Subdirectives

    defaultPage (method defaultPage)

      Attributes

        name -- (required) 

          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.

    page (method page)

      Attributes

        attribute -- 

          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.

        name -- (required) 

          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'.

        template -- 

          The name of a template that implements the page.



=== Added File Zope3/doc/zcml/namespaces.zope.org/browser/editform.stx ===
editform (function edit)



  Attributes

    layer -- (optional) 

      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'.

    title -- (optional) 

      The browser menu label for the edit form
      
      This attribute defaults to "Edit".

    name -- (required) 

      The name of the generated edit view.

    for -- (optional) 

      The interface this page (view) applies to.
      
      The view will be for all objects that implement this
      
      The schema is used if the for attribute is not specified.
      interface. If the for attribute is specified, the given
      interface must extend the schema.

    permission -- (required) 

      The permission needed to use the view.
      
      This attribute is required.

    menu -- (optional) 

      The browser menu to include the edit form in.
      
      Many views are included in menus. It's convenient to name
      the menu in the page directive, rather than having to give a
      separate menuItem directive.

    schema -- (required) 

      The schema from which the edir form is generated.
      
      A schema is an interface that includes fields.

    class -- (optional) 

      A class to provide custom widget defineitions or methods to be
      used by a custom template.

    template -- (optional) 

      An alternate template to use for the edit form.
      
      XXX Need to document how to extend the default.

    label -- (required) 

      A label to be used as the heading for the form.



=== Added File Zope3/doc/zcml/namespaces.zope.org/browser/i18n-resource.stx ===
i18n-resource (type zope.app.publisher.browser.I18nResource)

  Attributes

    default_language -- 



    name -- 



  Subdirectives

    translation (method translation)

      Attributes

        image -- 



        file -- 



        language -- 





=== Added File Zope3/doc/zcml/namespaces.zope.org/browser/icon.stx ===
icon (function IconDirective)

  Attributes

    layer -- 



    resource -- 



    name -- 



    file -- 



    alt -- 



    for -- 





=== Added File Zope3/doc/zcml/namespaces.zope.org/browser/menu.stx ===
menu (function              zope.app.publisher.browser.menuDirective)

  Define a new browser menu

  Attributes

    name -- 

      The name of the menu.
      
      This is, effectively, an id.

    title -- 

      A descriptive title for documentation purposes



=== Added File Zope3/doc/zcml/namespaces.zope.org/browser/menuItem.stx ===
menuItem (function          zope.app.publisher.browser.menuItemDirective)

  Attributes

    filter -- 



    description -- 



    for -- 



    title -- 



    action -- 



    menu -- 





=== Added File Zope3/doc/zcml/namespaces.zope.org/browser/menuItems.stx ===
menuItems (class zope.app.publisher.browser.menuItemsDirective)

  Define a group of browser menu items
  
  This directive is useful when many menu items are defined for
  the same interface and menu.

  Attributes

    menu -- (required) 

      The (name of the) menu the items are defined for

    for -- (optional) 

      The interface the menu items are defined for

  Subdirectives

    menuItem (method menuItem)

      Define a menu item within a group of menu items

      Attributes

        action -- (required) 

          The relative url to use if the item is selected
          
          The url is relative to the object the menu is being
          displayed for.

        filter -- (optional) 

          A condition for displaying the menu item
          
          The condition is given as a TALES expression. The
          expression has access to the variables:
          
          context -- The object the menu is being displayed for
          
          request -- The browser request
          
          nothing -- None
          
          The menu item will not be displayed if there is a filter
          and the filter evaluates to a false value.

        permission -- (optional) 

          The id of the permission needed access the item
          
          This can usually be infered by the system, however, doing
          so may be expensive. When displaying a menu, the system
          tries to traverse to the URLs given in each action to
          determine whether the url is accessable to the current
          user.  This can be avoided if the permission is given explicitly.

        description -- 

          A longer explaination of the menu item
          
          A UI may display this with the item or display it when the
          user requests more assistance.

        title -- (required) 

          The text to be displayed for the menu item



=== Added File Zope3/doc/zcml/namespaces.zope.org/browser/pages.stx ===
pages (class zope.app.publisher.browser.pages)

  Define multiple pages without repeating all of the parameters.
  
  The pages directive allows multiple page views to be defined
  without repeating the 'for', 'permission', 'class', 'layer',
  'allowed_attributes', and 'allowed_interface' attributes.

  Attributes

    layer -- (optional) 

      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'.

    for -- (required) 

      The interface this page (view) applies to.
      
      The view will be for all objects that implement this interface.
      
      To provide a page for all components, use
      "zope.interface.Interface".  To provide a page for all
      objects, use "*".

    allowed_attributes -- (optional) 

      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.

    permission -- (required) 

      The permission needed to use the view.

    allowed_interface -- (optional) 

      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.

    class -- 

      A class to use with a template, or to provide an attribute
      to publish.
      
      It's common to provide a class with methods to be used by
      the template to prevent including Python code in the template.

  Subdirectives

    page (method page)

      Attributes

        attribute -- (optional) 

          If a class is used, this is the name of the attribute to be used
          
          This is the attribute, usually a method, to be published as
          the page (view).  The fault is "__call__".

        title -- (optional) 

          The browser menu label for the page (view)
          
          This attribute must be supplied if a menu attribute is
          supplied.

        name -- (required) 

          The name of the view defined by the page.
          
          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.

        template -- 

          The name of a page template.
          
          Refers to a file containing a page template (must end in
          extension '.pt').

        menu -- (optional) 

          The browser menu to include the page (view) in.
          
          Many views are included in menus. It's convenient to name
          the menu in the page directive, rather than having to give a
          separate menuItem directive.



=== Added File Zope3/doc/zcml/namespaces.zope.org/browser/subeditform.stx ===
subeditform (function zope.app.browser.form.subedit)

  Attributes



=== Zope3/doc/zcml/namespaces.zope.org/browser/defaultView.stx 1.2 => 1.3 ===
--- Zope3/doc/zcml/namespaces.zope.org/browser/defaultView.stx:1.2	Mon Jun 10 19:27:36 2002
+++ Zope3/doc/zcml/namespaces.zope.org/browser/defaultView.stx	Tue Dec 31 13:26:48 2002
@@ -1 +1,19 @@
-The defaultView directive.
+defaultView (function zope.app.publisher.browser.defaultView)
+
+  Attributes
+
+    name -- 
+
+      The name of the view that should be the default.
+      
+      This name refers to view that should be the
+      view used by default (if no view name is supplied
+      explicitly).
+
+    for -- 
+
+      The interface this view is the default for.
+      
+      The view is the default view for the supplied
+      interface.
+


=== Zope3/doc/zcml/namespaces.zope.org/browser/page.stx 1.2 => 1.3 ===
--- Zope3/doc/zcml/namespaces.zope.org/browser/page.stx:1.2	Mon Jun 10 19:27:36 2002
+++ Zope3/doc/zcml/namespaces.zope.org/browser/page.stx	Tue Dec 31 13:26:48 2002
@@ -1 +1,105 @@
-The page subdirective of the view directive and resource directive.
+page (function page)
+
+  The page directive is used to create views that provide a
+  single url or page.
+  
+  The page directive creates a new view class from a given
+  template and/or class and registers it.
+
+  Attributes
+
+    layer -- (optional) 
+
+      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'.
+
+    name -- (required) 
+
+      The name of the page (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.
+
+    allowed_attributes -- (optional) 
+
+      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.
+
+    title -- (optional) 
+
+      The browser menu label for the page (view)
+      
+      This attribute must be supplied if a menu attribute is
+      supplied.
+
+    attribute -- (optional) 
+
+      The name of an attribute to publish.
+      
+      This is used to publish an attribute provided by a class,
+      instead of a template.
+      
+      This is the attribute, usually a method, to be published as
+      the page (view).  The default is "__call__".
+
+    permission -- (required) 
+
+      The permission needed to use the view.
+
+    for -- (required) 
+
+      The interface this page (view) applies to.
+      
+      The view will be for all objects that implement this interface.
+      
+      To provide a page for all components, use
+      "zope.interface.Interface".  To provide a page for all
+      objects, use "*".
+
+    template -- 
+
+      The name of a page template.
+      
+      Refers to a file containing a page template (must end in
+      extension '.pt').
+
+    menu -- (optional) 
+
+      The browser menu to include the page (view) in.
+      
+      Many views are included in menus. It's convenient to name
+      the menu in the page directive, rather than having to give a
+      separate menuItem directive.
+
+    allowed_interface -- (optional) 
+
+      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.
+      
+      Multiple interfaces, separated by whitespace, can be provided.
+
+    class -- 
+
+      A class to use with a template, or to provide an attribute
+      to publish.
+      
+      It's common to provide a class with methods to be used by
+      the template to prevent including Python code in the template.
+


=== Zope3/doc/zcml/namespaces.zope.org/browser/resource.stx 1.2 => 1.3 ===
--- Zope3/doc/zcml/namespaces.zope.org/browser/resource.stx:1.2	Mon Jun 10 19:27:36 2002
+++ Zope3/doc/zcml/namespaces.zope.org/browser/resource.stx	Tue Dec 31 13:26:48 2002
@@ -1 +1,42 @@
-The resource directive.
+resource (function zope.app.publisher.browser.resource)
+
+  Attributes
+
+    layer -- (optional) 
+
+      The layer the resource should be found in
+      
+      For information on layers, see the documentation for the
+      skin directive.
+      
+      Defaults to "default".
+
+    image -- 
+
+      The file containing the resource data.
+      
+      If the image attribute is used, then an image resource,
+      rather than a file resource will be created.
+
+    name -- (required) 
+
+      The name of the resource
+      
+      This is the name used in resource urls.  Resource urls are
+      of the form site/@@/resourcename, where site is the url of
+      "site", a folder with a service manager.
+      
+      We make resource urls site-relative (as opposed to
+      content-relative) so as not to defeat caches.
+
+    file -- 
+
+      The file containing the resource data.
+
+    permission -- (optional) 
+
+      The id of the permission needed to access the resource.
+      
+      If a permission isn't specified, the resource will always
+      be accessible.
+


=== Zope3/doc/zcml/namespaces.zope.org/browser/skin.stx 1.2 => 1.3 ===
--- Zope3/doc/zcml/namespaces.zope.org/browser/skin.stx:1.2	Mon Jun 10 19:27:36 2002
+++ Zope3/doc/zcml/namespaces.zope.org/browser/skin.stx	Tue Dec 31 13:26:48 2002
@@ -1 +1,17 @@
-The skin directive.
+skin (function zope.app.publisher.browser.skin)
+
+  Attributes
+
+    layers -- 
+
+      A list of names of layers.
+      
+      This should be in order of lookup. Usually one of the layers
+      has the same name as the skin, and the last skin should be
+      'default', unless you want to completely override all
+      views.
+
+    name -- 
+
+      The name of the skin.
+


=== Zope3/doc/zcml/namespaces.zope.org/browser/view.stx 1.5 => 1.6 ===
--- Zope3/doc/zcml/namespaces.zope.org/browser/view.stx:1.5	Sun Sep  1 15:21:50 2002
+++ Zope3/doc/zcml/namespaces.zope.org/browser/view.stx	Tue Dec 31 13:26:48 2002
@@ -1,48 +1,114 @@
-The view directive
+view (class zope.app.publisher.browser.view)
 
-See lib/python/Zope/App/Publisher/Browser/browser-meta.zcml
+  The view directive defines a viewe that has subpages.
+  
+  The pages provided by the defined view are accessed by first
+  traversing to the view name and then traversing to the page
+  name.
 
-Implemented in Zope.App.Publisher.Browser.metaConfigure.view
+  Attributes
 
-Attributes
+    layer -- (optional) 
 
-  * name
-  
-  * factory, a callable or list of callables 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.
-  
-  * for, the interface this view applies to
-  
-  * layer, defaults to 'default'
-  
-  * template, the name a page template (must end in extension .pt).
-    If you supply a template, you must also supply a name.
-  
-  * permission, a permission id
-  
-  * allowed_interface, must also supply a name or permission
-  
-  * allowed_attributes, must also supply a name or permission
-  
-Subdirectives
+      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'.
 
-  * page
-  
-    * name
-    
-    * attribute
-    
-    * permission
-  
-  * defaultPage
-  
-    * name
-    
-    * attribute
-    
-    * permission
+    title -- (optional) 
+
+      The browser menu label for the page (view)
+      
+      This attribute must be supplied if a menu attribute is
+      supplied.
+
+    name -- (required) 
+
+      The name of the view.
+      
+      The name shows up in URLs/paths. For example 'foo'.
+
+    for -- (required) 
+
+      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).
+
+    permission -- (required) 
+
+      The permission needed to use the view.
+
+    allowed_attributes -- (optional) 
+
+      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.
+
+    allowed_interface -- (optional) 
+
+      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.
+      
+      Multiple interfaces can be provided, separated by whitespace.
+
+    menu -- (optional) 
+
+      The browser menu to include the page (view) in.
+      
+      Many views are included in menus. It's convenient to name
+      the menu in the page directive, rather than having to give a
+      separate menuItem directive.
+
+    class -- (optional) 
+
+      A class that provides attributes used by the view.
+
+  Subdirectives
+
+    defaultPage (method defaultPage)
+
+      Attributes
+
+        name -- (required) 
+
+          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.
+
+    page (method page)
+
+      Attributes
+
+        attribute -- 
+
+          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.
+
+        name -- (required) 
+
+          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'.
+
+        template -- 
+
+          The name of a template that implements the page.
 
-    
-