[Checkins] SVN: grok/trunk/doc/reference/components.rst add initial docs for Permissions, Roles and Forms

[Kevin Teague]

Log message for revision 87817:
  add initial docs for Permissions, Roles and Forms

Changed:
  U   grok/trunk/doc/reference/components.rst

-=-
Modified: grok/trunk/doc/reference/components.rst
===================================================================
--- grok/trunk/doc/reference/components.rst	2008-06-27 00:35:48 UTC (rev 87816)
+++ grok/trunk/doc/reference/components.rst	2008-06-27 00:43:46 UTC (rev 87817)
@@ -559,9 +559,9 @@
         Returns an object and a sequence of names.
 	  
         The publisher calls this method at the end of each traversal path.
-	  	If the sequence of names is not empty, then a traversal step is made
-	  	for each name. After the publisher gets to the end of the sequence,
-	  	it will call browserDefault on the last traversed object.
+        If the sequence of names is not empty, then a traversal step is made
+        for each name. After the publisher gets to the end of the sequence,
+        it will call browserDefault on the last traversed object.
 	  
         The default behaviour in Grok is to return self.context for the object
         and 'index' for the default view name.
@@ -613,26 +613,192 @@
 Forms
 ~~~~~
 
+Forms inherit from the `grok.View` class. They are a specialized type of
+View that renders an HTML Form.
+
 :class:`grok.Form`
 ==================
 
-.. Do not forget about the form_fields class attribute!
+.. class:: grok.Form
 
+    Base class for forms.
+
+    .. attribute:: prefix
+    
+        Page-element prefix. All named or identified page elements in a
+        subpage should have names and identifiers that begin with a subpage
+        prefix followed by a dot.
+
+    .. method:: setPrefix(prefix):
+
+        Update the subpage prefix
+
+    .. attribute:: label
+    
+        A label to display at the top of a form.
+        
+    .. attribute:: status
+    
+        An update status message. This is normally generated by success or
+        failure handlers.
+    
+    .. attribute:: errors
+
+        Sequence of errors encountered during validation.
+
+    .. attribute:: form_result
+    
+        Return from action result method.
+
+    .. attribute:: form_reset
+    
+        Boolean indicating whether the form needs to be reset.
+
+    .. attribute:: form_fields
+    
+        The form's form field definitions.
+
+        This attribute is used by many of the default methods.
+
+    .. attribute:: widgets
+    
+        The form's widgets.
+
+        - set by setUpWidgets
+
+        - used by validate
+
+
+    .. method:: setUpWidgets(ignore_request=False):
+    
+        Set up the form's widgets.
+
+        The default implementation uses the form definitions in the
+        form_fields attribute and setUpInputWidgets.
+
+        The function should set the widgets attribute.
+
+    .. method:: validate(action, data):
+    
+        The default form validator
+
+        If an action is submitted and the action doesn't have it's own
+        validator then this function will be called.
+
+    .. attribute:: template
+    
+        Template used to display the form
+
+    .. method:: resetForm():
+    
+        Reset any cached data because underlying content may have changed.
+
+    .. method:: error_views():
+    
+        Return views of any errors.
+
+        The errors are returned as an iterable.
+
+    .. method:: applyData(obj, **data):
+    
+        Save form data to an object.
+
+        This returns a dictionary with interfaces as keys and lists of
+        field names as values to indicate which fields in which
+        schemas had to be changed in order to save the data.  In case
+        the method works in update mode (e.g. on EditForms) and
+        doesn't have to update an object, the dictionary is empty.
+
 :class:`grok.AddForm`
 =====================
 
+Add forms are used for creating new objects. The widgets for this form
+are not bound to any existing content or model object.
+
+.. class:: grok.AddForm
+
+    Base class for add forms.
+
 :class:`grok.EditForm`
 ======================
 
+Edit forms are used for editing existing objects. The widgets for this form
+are bound to the object set in the `context` attribute.
+
+.. class:: grok.EditForm
+
+    Base class for edit forms.
+
 :class:`grok.DisplayForm`
 =========================
 
+Display forms are used to display an existing object. The widgets for this
+form are bound to the object set in the `context` attribute.
+
+.. class:: grok.DisplayForm
+
+    Base class for display forms.
+
 Security
 ~~~~~~~~
 
 :class:`Permission`
 ===================
 
+Permissions are used to protect Views so that they can only be called by
+an authenticated principal. If a View in Grok does not have a `grok.require`
+directive declaring a permission needed to use the View, then the view will
+be public.
+
+.. class:: grok.Permission
+
+    Base class for permissions. You must specify a unique name for every
+    permission using the `grok.name` directive. The convention for ensuring
+    uniqueness is to prefix your permission name with the name of your
+    Grok package followed by a dot, e.g. 'mypackage.MyPermissionName'.
+
+    .. attribute:: id
+    
+        Id as which this permission will be known and used. This is set
+        to the value specified in the `grok.name` directive.
+
+    .. attribute:: title
+
+        Human readable identifier for this permission.
+
+    .. attribute:: description
+
+        Description of the permission.
+
+    **Directives:**
+
+    :func:`grok.name(name)`
+    
+        Required. Identifies the unique name (also used as the id) of the
+        permission.
+
+    :func:`grok.title(title)`
+
+        Optional. Stored as the title attribute for this permission.
+    
+    :func:`grok.description(description)`
+
+        Optional. Stored as the description attribute for this permission.
+
+**Example 1: Define a new Permission and use it to protect a View**
+
+.. code-block:: python
+
+    import grok
+    import zope.interface
+    
+    class Read(grok.Permission):
+        grok.name('mypackage.Read')
+
+    class Index(grok.View):
+        grok.context(zope.interface.Interface)
+        grok.require('mypackage.Read')
+
 :func:`grok.define_permission` -- define a permission
 =====================================================
 
@@ -664,3 +830,107 @@
 
 :class:`Role`
 =============
+
+Roles provide a way to group together a collection of permissions. Principals
+(aka Users) can be granted a Role which will allow them to access all Views
+protected by the Permissions that the Role contains.
+
+.. class:: grok.Role
+
+    Base class for roles.
+
+    .. attribute:: id
+    
+        Id as which this role will be known and used. This is set
+        to the value specified in the `grok.name` directive.
+
+    .. attribute:: title
+
+        Human readable identifier for this permission.
+
+    .. attribute:: description
+
+        Description of the permission.
+
+    **Directives:**
+
+    :func:`grok.name(name)`
+
+        Required. Identifies the unique name (also used as the id) of the
+        role.
+
+    :func:`grok.permissions(permissions)`
+
+        Required. Declare the permissions granted to this role.
+
+    :func:`grok.title(title)`
+
+        Optional. Stored as the title attribute for this role.
+
+    :func:`grok.description(description)`
+
+        Optional. Stored as the description attribute for this role.
+
+**Example 1: Define a new 'paint.Artist' Role and assign it to the 'paint.grok' principal**
+
+.. code-block:: python
+
+    import grok
+    import zope.interface
+
+    class ViewPermission(grok.Permission):
+        grok.name('paint.ViewPainting')
+
+    class EditPermission(grok.Permission):
+        grok.name('paint.EditPainting')
+
+    class ErasePermission(grok.Permission):
+        grok.name('paint.ErasePainting')
+
+    class ApprovePermission(grok.Permission):
+        grok.name('paint.ApprovePainting')
+
+    class Artist(grok.Role):
+        """
+        An Artist can view, create and edit paintings. However, they can
+        not approve their painting for display in the Art Gallery Cave.
+        """
+        grok.name('paint.Artist')
+        grok.title('Artist')
+        grok.description('An artist owns the paintings that they create.')
+        grok.permissions(
+            'paint.ViewPainting', 'paint.EditPainting', 'paint.ErasePainting')
+
+    class CavePainting(grok.View):
+        grok.context(zope.interface.Interface)
+        grok.require(ViewPermission)
+
+        def render(self):
+            return 'What a beautiful painting.'
+
+    class EditCavePainting(grok.View):
+        grok.context(zope.interface.Interface)
+        grok.require(EditPermission)
+
+        def render(self):
+            return 'Let\'s make it even prettier.'
+
+    class EraseCavePainting(grok.View):
+        grok.context(zope.interface.Interface)
+        grok.require(ErasePermission)
+
+        def render(self):
+            return 'Oops, mistake, let\'s erase it.'
+
+    class ApproveCavePainting(grok.View):
+        grok.context(zope.interface.Interface)
+        grok.require(ApprovePermission)
+
+        def render(self):
+            return 'Painting owners cannot approve their paintings.'
+
+    # The app variable will typically be your Application instance,
+    # but could also be a container within your application.
+    from zope.securitypolicy.interfaces import IPrincipalRoleManager
+    IPrincipalRoleManager(app).assignRoleToPrincipal(
+       'paint.Artixt', 'paint.grok')