[CMF-checkins] CVS: CMF/CMFCore/interfaces - portal_actions.py:1.12

[Yvo Schubbe]

Update of /cvs-repository/CMF/CMFCore/interfaces
In directory cvs.zope.org:/tmp/cvs-serv2437/CMFCore/interfaces

Modified Files:
	portal_actions.py 
Log Message:
- updated interfaces/portal_actions.py to document the current state of Actions
- made implementations of OldstyleActionProvider explicit
- some whitespace and import cleanup


=== CMF/CMFCore/interfaces/portal_actions.py 1.11 => 1.12 ===
--- CMF/CMFCore/interfaces/portal_actions.py:1.11	Thu Feb 13 03:31:02 2003
+++ CMF/CMFCore/interfaces/portal_actions.py	Fri Nov 14 03:34:56 2003
@@ -24,80 +24,107 @@
 
 
 class portal_actions(Interface):
-    '''Gathers a list of links which the user is allowed to view according to
+    """ Gathers a list of links which the user is allowed to view according to
     the current context.
-    '''
+    """
     id = Attribute('id', 'Must be set to "portal_actions"')
 
-    # listActionProviders__roles__ = ( 'Manager', )
     def listActionProviders():
-        """ Lists all action provider names registered with the 
-        actions tool.
+        """ List the ids of all Action Providers queried by this tool.
+
+        Permission -- Manage portal
+
+        Returns -- Tuple of Action Provider ids
+        """
+
+    def addActionProvider(provider_name):
+        """ Add an Action Provider id to the providers queried by this tool.
+
+        A provider must implement the ActionProvider Interface.
+        OldstyleActionProviders are currently also supported.
+
+        The provider is only added if the actions tool can find the object
+        corresponding to the provider_name.
+
+        Permission -- Manage portal
+        """
+
+    def deleteActionProvider(provider_name):
+        """ Delete an Action Provider id from providers queried by this tool.
+
+        The deletion only takes place if provider_name is actually found among
+        the known action providers.
+
+        Permission -- Manage portal
         """
 
-    # addActionProvider__roles__ = ( 'Manager', )
-    def addActionProvider( provider_name ):
-        """ Add a new action provider to the providers known by the actions
-        tool. A provider must implement listActions.
-        The provider is only added is the actions tool can find the 
-        object corresponding to the provider_name
-        """
-
-    # deleteActionProvider__roles__ = ( 'Manager', )
-    def deleteActionProvider( provider_name ):
-        """ Deletes an action provider name from the providers known to
-        the actions tool. The deletion only takes place if provider_name
-        is actually found among the known action providers.
-        """
-
-    # listFilteredActionsFor__roles__ = None
-    def listFilteredActionsFor(object):
-        '''Gets all actions available to the user and returns a mapping
-        containing a list of user actions, folder actions, object actions,
-        and global actions.  Each action has the following keys:
-           name: An identifying action name
-           url: The URL to visit to access the action
-           permissions: A list. The user must have at least of the listed
-             permissions to access the action.  If the list is empty,
-             the user is allowed.  (Note that listFilteredActions() filters
-             out actions according to this field.)
-           category: One of "user", "folder", "object", or "globals".
-        '''
-
-    # listFilteredActions__roles__ = None
-    def listFilteredActions():
-        '''Gets all actions available to the user in no particular context.
-        '''
+    def listFilteredActionsFor(object=None):
+        """ List all actions available to the user.
+
+        Each action has the following keys:
+
+        - name: An identifying action name
+
+        - url: The URL to visit to access the action
+
+        - permissions: A list. The user must have at least one of the listed
+          permissions to access the action. If the list is empty, the user is
+          allowed. (Note that listFilteredActionsFor() filters out actions
+          according to this field.)
+
+        - category: One of "user", "folder", "object", "global" or "workflow"
+
+        Permission -- Always available
+
+        Returns -- Dictionary of category / action list pairs.
+        """
+
+    def listFilteredActions(object=None):
+        """ Deprecated alias of listFilteredActionsFor.
+        """
 
 
 class ActionProvider(Interface):
-    '''The interface expected of an object that can provide actions.
-    '''
+    """ The interface expected of an object that can provide actions.
+    """
 
-    # listActions__roles__ = ()  # No permission.
     def listActions(info=None):
-        """ Return all the actions defined by a provider.
+        """ List all the actions defined by a provider.
 
-        The info argument is currently used by 'Oldstyle CMF Discussion Tool'
-        and 'CMF Workflow Tool'.
+        The info argument is currently used by 'CMF Types Tool'. It contains
+        at least a 'content' attribute.
 
         Returns -- Tuple of ActionInformation objects
+        """
+
 
-        Oldstyle dictionary actions are currently also supported:
-        Returns a list of mappings describing actions.  Each action
-        should contain the keys "name", "url", "permissions", and
+class OldstyleActionProvider(Interface):
+    """ Deprecated interface expected of an object that can provide actions.
+
+    Still used by 'Oldstyle CMF Discussion Tool' and 'CMF Workflow Tool'.
+    """
+
+    def listActions(info):
+        """ List all the actions defined by a provider.
+
+        Each action should contain the keys "name", "url", "permissions" and
         "category", conforming to the specs outlined in
-        portal_actions.listFilteredActionsFor().  The info argument
-        contains at least the following attributes, some of which
-        may be set to "None":
-
-          isAnonymous
-          portal
-          portal_url
-          folder
-          folder_url
-          content
-          content_url
-          The new way of doing this is....
-        """
+        portal_actions.listFilteredActionsFor(). The info argument contains
+        at least the following attributes, some of which may be set to "None":
 
+        - isAnonymous
+
+        - portal
+
+        - portal_url
+
+        - folder
+
+        - folder_url
+
+        - content
+
+        - content_url
+
+        Returns -- Tuple of mappings describing actions
+        """