Back to index

plone3  3.1.7
_tools.py
Go to the documentation of this file.
00001 ##############################################################################
00002 #
00003 # Copyright (c) 2005 Zope Corporation and Contributors. All Rights Reserved.
00004 #
00005 # This software is subject to the provisions of the Zope Public License,
00006 # Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
00007 # THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
00008 # WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00009 # WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
00010 # FOR A PARTICULAR PURPOSE.
00011 #
00012 ##############################################################################
00013 """ CMFCore tool interfaces.
00014 
00015 $Id: _tools.py 78659 2007-08-07 09:33:59Z wichert $
00016 """
00017 
00018 from zope.interface import Interface
00019 from zope.interface import Attribute
00020 
00021 _marker = object()
00022 
00023 
00024 #
00025 #   Action subsystem interfaces
00026 #
00027 class IActionsTool(Interface):
00028 
00029     """ Generate the list of "actions" which the user is allowed to perform.
00030 
00031     o Synthesize this list from the actions managed by a set of "action
00032       providers".
00033     """
00034 
00035     id = Attribute('id',
00036             """ The ID of the tool.
00037 
00038             o Must be set to "portal_actions"
00039             """,
00040             )
00041 
00042     def listActionProviders():
00043         """ Return a sequence of names of all IActionProvider utilities
00044             registered with this tool.
00045 
00046         o The returned list of names will be a subset of the set available
00047           via 'zapi.getUtilitiesFor(IActionProvider)' (which returns
00048           '(name, value)' tuples).
00049 
00050         o Deprecated: In the future, expect to use 'getUtilitiesFor' instead
00051           (presuming either that ordering either doesn't matter or that
00052           ordering is supported by the utility registry).
00053 
00054         o Permission:  Manage portal
00055         """
00056 
00057     def addActionProvider(provider_name):
00058         """ Register an IActionProvider to the set queried by this tool.
00059 
00060         o 'provider_name' is appended to the set of names already registered
00061           with the tool.
00062 
00063         o Raise ComponentLookupError if no utility of that name is registered
00064           for IActionProvider.
00065 
00066         o Deprecated: In the future, expect to use 'getUtilitiesFor' instead
00067           (presuming either that ordering either doesn't matter or that
00068           ordering is supported by the utility registry).
00069 
00070         o Permission:  Manage portal
00071         """
00072 
00073     def deleteActionProvider(provider_name):
00074         """ Remove an IActionProvider from the set queried by this tool.
00075 
00076         o Return silently if 'provider_name' is not already registered with
00077           the tool.
00078 
00079         o Deprecated: In the future, expect to use 'getUtilitiesFor' instead
00080           (presuming either that ordering either doesn't matter or that
00081           ordering is supported by the utility registry).
00082 
00083         o Permission:  Manage portal
00084         """
00085 
00086     def listFilteredActionsFor(object=None):
00087         """ Map actions available to the user by category.
00088 
00089         o Returned mapping will have category IDs as keys, and sequences
00090           of IActionInformation objects as the corresponding values for each
00091           category.
00092 
00093         o Categories may be arbitrarily extended.
00094 
00095         o Permission:  Public
00096         """
00097 
00098 
00099 class IActionProvider(Interface):
00100 
00101     """ Objects that can be queried for actions.
00102     """
00103 
00104     def listActions(info=None, object=None):
00105         """ List known action informations.
00106 
00107         o Return a sequence of IActionInformation intances.
00108 
00109         o Both the 'object' and the 'info' arguments are deprecated and
00110           ignored (use 'listActionInfos' to filter actions by context).
00111         """
00112 
00113     def listActionInfos(action_chain=None, object=None, check_visibility=True,
00114                         check_permissions=True, check_condition=True, max=None):
00115         """ Return a sequence of IActionInformation matching the given criteria.
00116 
00117         o 'action_chain' is a sequence of one or more action paths
00118           (e.g. 'object/view');  each path is formatted as
00119           'category_id/action_id'.  If specified, only matching actions will
00120           be returned, and in the given order (paths with no matches are
00121           ignored silently).
00122 
00123         o If 'object' is specified, only actions specific to that object
00124           are included.
00125 
00126         o If 'check_visibility' is True, return only actions whos "visible"
00127           flag is set.
00128 
00129         o If 'check_permissions' is True, return only actions for whose
00130           permissions the current user is authorized.
00131 
00132         o If 'check_condition' is True, return only actions whose condition
00133           expression evaluates True.
00134 
00135         o If 'max' is specified, return only the first 'max' Actions.
00136 
00137         o Permission:  Public (but not URL-publishable)
00138         """
00139 
00140     def getActionInfo(action_chain, object=None, check_visibility=False,
00141                       check_condition=False):
00142         """ Return the first IActionInformation matching the given criteria.
00143 
00144         o If no action is found matching the criteria, raise ValueError.
00145 
00146         o 'action_chain' is a sequence of one or more action paths
00147           (e.g. 'object/view');  each path is formatted as
00148           'category_id/action_id'.  If specified, only matching actions will
00149           be returned, and in the given order (paths with no matches are
00150           ignored silently).
00151 
00152         o If 'check_visibility' is True, return only actions whos "visible"
00153           flag is set.
00154 
00155         o If 'check_condition' is True, return only actions whose condition
00156           expression evaluates True.
00157 
00158         o Permission:  Public
00159         """
00160 
00161 
00162 class IActionCategory(Interface):
00163 
00164     """ Group of IAction objects and child categories.
00165     """
00166 
00167     def listActions():
00168         """ Return a sequence of IActionInformation defined by this category
00169 
00170         o Include actions defined by subcategories.
00171 
00172         o Permission:  Private (Python only)
00173         """
00174 
00175 
00176 class IAction(Interface):
00177 
00178     """ Specification for an action.
00179     """
00180 
00181     def getInfoData():
00182         """ Return a lazy mapping of the data needed to create an
00183             IActionInformation.
00184 
00185         o Returned value is actually a tuple, '(lazy_map, lazy_keys)'.
00186 
00187         o Default keys are: 'id', 'category', 'title', 'description', 'url',
00188           'icon', 'available', 'permissions' and 'visible'.
00189 
00190         o Instead of computed values callable expression objects or methods
00191           are returned. For performance reasons, these objects are called
00192           later and only if the values are actually needed. The keys for all
00193           these lazy values are registered in a separate list.
00194         """
00195 
00196 
00197 class IActionInfo(Interface):
00198 
00199     """ A lazy dictionary for Action infos.
00200 
00201     o Each ActionInfo object has the following keys:
00202 
00203       - id (string): not unique identifier
00204 
00205       - title (string)
00206 
00207       - url (string): URL to access the action
00208 
00209       - category (string): one of "user", "folder", "object", "global",
00210         "workflow" or a custom category
00211 
00212       - visible (boolean)
00213 
00214       - available (boolean): the result of checking the condition
00215 
00216       - allowed (boolean): the result of checking permissions;
00217         The user must have at least one of the listed permissions to access
00218         the action. If the list is empty, the user is allowed.
00219     """
00220 
00221 
00222 #
00223 #   Caching policy tool interfaces
00224 #
00225 class ICachingPolicy(Interface):
00226 
00227     def getPolicyId():
00228         """
00229         """
00230 
00231     def getPredicate():
00232         """
00233         """
00234 
00235     def getMTimeFunc():
00236         """
00237         """
00238 
00239     def getMaxAgeSecs():
00240         """
00241         """
00242 
00243     def getSMaxAgeSecs():
00244         """
00245         """
00246 
00247     def getNoCache():
00248         """
00249         """
00250 
00251     def getNoStore():
00252         """
00253         """
00254 
00255     def getMustRevalidate():
00256         """
00257         """
00258 
00259     def getProxyRevalidate():
00260         """
00261         """
00262 
00263     def getPublic():
00264         """
00265         """
00266 
00267     def getPrivate():
00268         """
00269         """
00270 
00271     def getNoTransform():
00272         """
00273         """
00274 
00275     def getVary():
00276         """
00277         """
00278 
00279     def getETagFunc():
00280         """
00281         """
00282 
00283     def getEnable304s():
00284         """
00285         """
00286 
00287     def getLastModified():
00288         """Should we set the last modified header?
00289         """
00290 
00291     def getPreCheck():
00292         """
00293         """
00294 
00295     def getPostCheck():
00296         """
00297         """
00298     
00299     def testPredicate(expr_context):
00300         """Does this request match our predicate?
00301         """
00302 
00303     def getHeaders(expr_context):
00304         """Does this request match our predicate?
00305 
00306         If so, return a sequence of caching headers as (key, value) tuples.
00307         Otherwise, return an empty sequence.
00308         """
00309 
00310 
00311 class ICachingPolicyManager(Interface):
00312 
00313     """ Compute HTTP cache headers for skin methods.
00314     """
00315 
00316     id = Attribute('id',
00317             """ The ID of the tool.
00318 
00319             o BBB:  for use in 'getToolByName';  in the future, prefer
00320                     'zapi.getUtility(ICachingPolicyManager)'.
00321 
00322             o Must be set to 'caching_policy_manager'.
00323             """,
00324             )
00325 
00326     def getHTTPCachingHeaders(content, view_method, keywords, time=None):
00327         """ Update HTTP caching headers in REQUEST
00328 
00329         o 'content' is the content object being published.
00330 
00331         o 'view_method' is the name of the view being published
00332 
00333         o 'keywords' is a set of extra keywords modifying the view.
00334 
00335         o If 'time' is supplied, use it instead of the current time
00336           (for reliable testing).
00337         """
00338 
00339 
00340 #
00341 #   Catalog tool interfaces
00342 #
00343 class ICatalogTool(Interface):
00344 
00345     """Wrap the "stock" ZCatalog with custom behavior for the CMF.
00346     """
00347 
00348     id = Attribute('id', 'Must be set to "portal_catalog"')
00349 
00350     # searchResults inherits security assertions from ZCatalog.
00351     def searchResults(REQUEST=None, **kw):
00352         """ Decorate ZCatalog.searchResults() with extra arguments
00353 
00354         o The extra arguments that the results to what the user would be
00355           allowed to see.
00356         """
00357 
00358     # __call__ inherits security assertions from ZCatalog.
00359     def __call__(REQUEST=None, **kw):
00360         """Alias for searchResults().
00361         """
00362 
00363     def unrestrictedSearchResults(REQUEST=None, **kw):
00364         """Calls ZCatalog.searchResults() without any CMF-specific processing.
00365 
00366         o Permission:  Private (Python only)
00367         """
00368 
00369     def indexObject(object):
00370         """ Add 'object' to the catalog.
00371 
00372         o Permission:  Private (Python only)
00373         """
00374 
00375     def unindexObject(object):
00376         """ Remove 'object' from the catalog.
00377 
00378         o Permission:  Private (Python only)
00379         """
00380 
00381     def reindexObject(object, idxs=[], update_metadata=True):
00382         """ Update 'object' in catalog.
00383 
00384         o 'idxs', if passed, is a list of specific indexes to update
00385           (by default, all indexes are updated).
00386 
00387         o If 'update_metadata' is True, then update the metadata record
00388           in the catalog as well.
00389 
00390         o Permission:  Private (Python only)
00391         """
00392 
00393 
00394 class IIndexableObjectWrapper(Interface):
00395 
00396     """ Wrapper for catalogued objects, for indexing "virtual" attributes.
00397     """
00398 
00399     def allowedRolesAndUsers():
00400         """ Return a sequence roles and users with View permission.
00401 
00402         o PortalCatalog indexes this sequence to allow filtering out items
00403           a user is not allowed to see.
00404         """
00405 
00406 
00407 #
00408 #   PUT factory handler interfaces
00409 #
00410 class IContentTypeRegistryPredicate(Interface):
00411 
00412     """ Match a given name/typ/body to a portal type.
00413 
00414     The registry will call the predictate's 'edit' method, passing the fields
00415     of the record.
00416     """
00417 
00418     def __call__(name, typ, body):
00419         """ Return true if the rule matches, else false. """
00420 
00421     def getTypeLabel():
00422         """ Return a human-readable label for the predicate type. """
00423 
00424     def predicateWidget():
00425         """ Return a snippet of HTML suitable for editing the predicate.
00426 
00427         o This method may be defined via DTMLFile or PageTemplateFile
00428           (the tool will call it appropriately, if it is DTML).
00429 
00430         o The snippet should arrange for values to be marshalled by
00431           ZPublisher as a ':record', with the ID of the predicate as the
00432           name of the record.
00433         """
00434 
00435 
00436 class IContentTypeRegistry(Interface):
00437 
00438     """ Apply policy mapping PUT arguments to a CMF portal type.
00439     """
00440 
00441     def findTypeName(name, typ, body):
00442         """ Return the the portal type (an ID) for a PUT request.
00443 
00444         o 'name' is the filename supplied as the end of the path of the
00445           PUT request.
00446 
00447         o 'typ' is the MIME type for the request (which may have been guessed
00448           already from the extension or the body).
00449 
00450         o 'body' is the actual payload of the PUT request.
00451 
00452         o Return None if no match found.
00453         """
00454 
00455 
00456 #
00457 #   Cookie crumbler interfaces.
00458 #
00459 class ICookieCrumbler(Interface):
00460 
00461     """Reads cookies during traversal and simulates the HTTP auth headers.
00462     """
00463 
00464 
00465 #
00466 #   Discussion tool interfaces.
00467 #
00468 class IOldstyleDiscussionTool(Interface):
00469 
00470     """ Links content to discussions.
00471     """
00472 
00473     id = Attribute('id',
00474             """ The tool's ID.
00475 
00476             o BBB:  for use in 'getToolByName';  in the future, prefer
00477               'zapi.getUtility(IDiscussionTool)'.
00478 
00479             o Must be set to 'portal_discussion'.
00480             """)
00481 
00482     def getDiscussionFor(content):
00483         """ Return an IDiscussionItemContainer for 'content'.
00484 
00485         o Create the IDC if necessary.
00486 
00487         o Raise ValueError if discussion is not allowed on 'content'.
00488 
00489         o Permission:  Public
00490         """
00491 
00492     def isDiscussionAllowedFor(content):
00493         """ Return True discussion is allowed for 'content', else False.
00494 
00495         o Result may be looked up from an object-specific value, or by place,
00496           or from a site-wide policy.
00497 
00498         o Permission:  Public
00499         """
00500 
00501 
00502 class IDiscussionTool(IOldstyleDiscussionTool):
00503 
00504     """ Links content to discussions.
00505     """
00506 
00507     def overrideDiscussionFor(content, allowDiscussion):
00508         """ Override discussability for the given object or clear the setting.
00509 
00510         o 'allowDiscussion' may be True, False, or None.
00511 
00512         o If 'allowDiscussion' is None, then clear any overridden setting for
00513           discussability, letting the site's default policy apply.
00514 
00515         o Otherwise, set the override to match 'allowDiscussion'.
00516 
00517         o Permission:  PUblic XXX?  Should be ManageContent, or something.
00518         """
00519 
00520 
00521 #
00522 #   MemberData tool interfaces
00523 #
00524 class IMemberDataTool(Interface):
00525 
00526     """ Decorate user objects with site-local data.
00527     """
00528 
00529     id = Attribute('id',
00530             """ The tool's ID.
00531 
00532             o BBB:  for use in 'getToolByName';  in the future, prefer
00533               'zapi.getUtility(IMemberDataTool)'.
00534 
00535             o Must be set to 'portal_memberdata'
00536             """,
00537             )
00538 
00539     def wrapUser(user):
00540         """Returns an IMember corresponding to the given user object.
00541 
00542         o Permission:  Private (Python-only)
00543         """
00544 
00545     def getMemberDataContents():
00546         """ Returns a list containing a dictionary with information
00547         about the _members BTree contents
00548 
00549         o The key 'member_count' is the total number of member instances
00550           stored in the memberdata-tool
00551 
00552         o The key 'orphan_count' is the number of member instances
00553           that for are no longer in the underlying acl_users user folder.
00554 
00555         o The result is designed to be iterated over in a dtml-in
00556 
00557         o XXX:  why a sequence?
00558 
00559         o Permission:  Private (Python-only)
00560         """
00561 
00562     def pruneMemberDataContents():
00563         """ Delete member data of all members not findable in acl_users.
00564 
00565         o Compare the user IDs stored in the member data tool with the
00566           list in the actual underlying acl_users and delete any records whose
00567           user cannot be found.
00568 
00569         o Permission:  Private (Python only)
00570         """
00571 
00572     def searchMemberData(search_param, search_term, attributes=()):
00573         """ Return a sequence of mappings of memberdata for the given criteria.
00574 
00575         o 'search_param' is the property ID to be searched.
00576 
00577         o 'search_term' is the property value to be searched.
00578 
00579         o 'attributes', if passed, controls the keys in the returned mappings;
00580           by default the returned keys are 'username' and 'email'.
00581 
00582         o XXX:  that default is silly;  if it is truly needed, then it should
00583           be the default value of the 'attributes' argument.
00584 
00585         o Permission:  Private (Python only)
00586         """
00587 
00588     def registerMemberData(m, id):
00589         """ Add the given member data to the _members btree.
00590 
00591         o 'm' is an object whose attributes are the memberdata for the member.
00592 
00593         o 'id' is the userid of the member.
00594 
00595         o Add the record late as possible to avoid side effect transactions
00596           and to reduce the necessary number of entries.
00597 
00598         o XXX: these argument names are silly;  can we use more sensible
00599           ones (i.e., does anyone actually depend on them)?
00600 
00601         o Permission:  Private (Python only)
00602         """
00603 
00604     def deleteMemberData(member_id):
00605         """ Delete member data of specified member.
00606 
00607         o Return True if a record was deleted, else False.
00608 
00609         o Permission:  Private (Python only)
00610         """
00611 
00612 class IMemberData(Interface):
00613 
00614     """ MemberData interface.
00615     """
00616 
00617     def setProperties(properties=None, **kw):
00618         """ Allow the authenticated member to update his/her member data.
00619 
00620         o 'properties', if passed, is a mapping of the IDs and values of
00621           the properties to be changed.
00622 
00623         o The method may also be invoked via keyword arguments (in this
00624           case, do *not* pass 'properties').
00625 
00626         o Permission:  Set own properties
00627         """
00628 
00629 
00630 #
00631 #   Membership tool interfaces
00632 #
00633 class IMembershipTool(Interface):
00634 
00635     """ Manage policy of how and where to store and retrieve members and
00636         their member folders.
00637     """
00638 
00639     id = Attribute('id',
00640             """ The tool's ID.
00641 
00642             o Must be set to 'portal_membership'.
00643             """)
00644 
00645     def setPassword(password, domains=None):
00646         """ Allow the authenticated member to set his/her own password.
00647 
00648         Permission:  Set own password
00649         """
00650 
00651     def getAuthenticatedMember():
00652         """ Return the currently authenticated member object
00653 
00654         o If no valid credentials are passed in the request, return
00655           the Anonymous User.
00656 
00657         o Permission:  Public
00658         """
00659 
00660     def isAnonymousUser():
00661         """ Return True if no valid credentials are passed in the requeset.
00662 
00663         o Permission:  Public
00664         """
00665 
00666     def checkPermission(permissionName, object, subobjectName=None):
00667         """ Return True if the current user has the given permission on
00668             the given object or subobject.
00669 
00670         o 'permissionName' is the string identifying the permission.
00671 
00672         o 'object' is the object being checked.
00673 
00674         o 'subobjectName', if passed, is the attribute name to be checked;
00675           if None, test the main object itself.
00676 
00677         o Permission:  Public
00678         """
00679 
00680     def credentialsChanged(password, REQUEST=None):
00681         """ Notify the authentication mechanism that this user has
00682             changed passwords.
00683 
00684         o The authentication mechanism can use this notification to update
00685           the authentication cookie.
00686 
00687         o Note that this call should *not* cause any change at all to user
00688           databases.
00689 
00690         o XXX:  should be an event.
00691 
00692         o XXX:  should this be in scope for this tool?  Or should it be
00693                 done by the view class for the password update view?
00694 
00695         Permission:  Public # XXX?
00696         """
00697 
00698     def getMembersFolder():
00699         """ Return the folderish object which contains membmer folders.
00700 
00701         o Return None if no members folder is set or if the specified
00702           folder doesn't exist.
00703 
00704         o Permission:  Public
00705         """
00706 
00707     def getHomeFolder(id=None, verifyPermission=False):
00708         """ Return a member's home folder object or None.
00709 
00710         o 'id', if passed, is the ID of the member whose folder should be
00711           returned;  if not passed, use the currently-authenticated member.
00712 
00713         o If 'verifyPermission' is True, return None when the user
00714           doesn't have the View permission on the folder.
00715 
00716         o Permission:  Public
00717         """
00718 
00719     def getHomeUrl(id=None, verifyPermission=0):
00720         """ Return the URL to a member's home folder or None.
00721 
00722         o 'id', if passed, is the ID of the member whose folder should be
00723           returned;  if not passed, use the currently-authenticated member.
00724 
00725         o If 'verifyPermission' is True, return None when the user
00726           doesn't have the View permission on the folder.
00727 
00728         Permission:  Public
00729         """
00730 
00731     def getMemberById(id):
00732         """ Returns the given IMember.
00733 
00734         o Permission:  Manage users
00735         """
00736 
00737     def listMemberIds():
00738         """ Return a sequence of ids of all members.
00739 
00740         o This may eventually be replaced with a set of methods for querying
00741           pieces of the list rather than the entire list at once.
00742 
00743         o Permission:  Manage users
00744         """
00745 
00746     def listMembers():
00747         """ Return a sequence of all IMembers.
00748 
00749         o This may eventually be replaced with a set of methods for querying
00750           pieces of the list rather than the entire list at once.
00751 
00752         o Permission:  Manage users
00753         """
00754 
00755     def getCandidateLocalRoles(obj):
00756         """ Return a sequence local roles assignable by the current user for
00757             a given object.
00758 
00759         o 'obj' is the object to which role assignments may be made.
00760 
00761         o Permission:  Public # XXX?
00762         """
00763 
00764     def setLocalRoles(obj, member_ids, member_role, reindex=True):
00765         """ Assign a local role on an item to one or more members.
00766 
00767         o 'obj' is the object on which to assign the role.
00768 
00769         o 'member_ids' is a sequence of user IDs to which to assign the role.
00770 
00771         o 'member_role' is the name of the role to assign.
00772 
00773         o If 'reindex' is True, then reindex the security-related attributes
00774           of the object and all subobjects.
00775 
00776         o Raise Unauthorized if the currently-authenticated member cannot
00777           assign 'member_role' on 'obj'.
00778 
00779         o Permission:  Public # XXX?
00780         """
00781 
00782     def deleteLocalRoles(obj, member_ids, reindex=True, recursive=False):
00783         """ Remove local roles of specified members from an object.
00784 
00785         o 'obj' is the object on which to remove the role.
00786 
00787         o 'member_ids' is a sequence of user IDs from which to remove the role.
00788 
00789         o If 'reindex' is True, then reindex the security-related attributes
00790           of the object and all subobjects.
00791 
00792         o if 'recursive' is True, recurse over all subobjects of 'object'.
00793 
00794         o Raise Unauthorized if the currently-authenticated member cannot
00795           assign 'member_role' on 'obj'.
00796 
00797         Permission:  Public
00798         """
00799 
00800     def addMember(id, password, roles, domains):
00801         """ Adds a new member to the user folder.
00802 
00803         o Security checks will have already been performed. Called by
00804           the registration tool.
00805 
00806         Permission:  Private (Python only)
00807         """
00808 
00809     def deleteMembers(member_ids, delete_memberareas=1, delete_localroles=1):
00810         """ Remove specified members from the site.
00811 
00812         o Returns a sequence of member_ids of members actually deleted.
00813 
00814         o Remove the members from the user folder.
00815 
00816         o 'member_ids' is a sequence of one or more user IDs to remove.
00817 
00818         o Remove corresponding member data in the memberdata tool.
00819 
00820         o If 'delete_memberareas' is True, delete members' home folders
00821           including all content items.
00822 
00823         o If 'delete_localroles' is true, recursively delete members' local
00824           roles, starting from the site root.
00825 
00826         o Permission:  Manage users
00827         """
00828 
00829     def getPortalRoles():
00830         """ Return a sequence of role names defined by the portal itself.
00831 
00832         o Returned role names are those understood by the portal object.
00833 
00834         o Permission:  Manage portal
00835         """
00836 
00837     def setRoleMapping(portal_role, userfolder_role):
00838         """ Register a mapping of a role defined by the portal to a role
00839             coming from outside user sources.
00840 
00841         o Permission:  Manage portal
00842         """
00843 
00844     def getMappedRole(portal_role):
00845         """ Returns a mapped role name corresponding to 'portal_role', or
00846             the empty string if no mapping exists.
00847 
00848         o Mappings are defined via 'setRoleMapping'.
00849 
00850         o Permission:  Manage portal
00851         """
00852 
00853     def getMemberareaCreationFlag():
00854         """ Return True if the membership tool will create a member area for
00855             a user at login.
00856 
00857         o Permission:  Manage portal
00858         """
00859 
00860     def setMemberareaCreationFlag():
00861         """ Toggle the policy flag for create a member areas at login.
00862 
00863         o XXX:  Toggle is a weak semantic here;  shouldn't we be passing
00864                 the value we want the flag to have?
00865 
00866         o Permission:  Manage portal
00867         """
00868 
00869     def createMemberArea(member_id=''):
00870         """ Return a member area for the given member, creating if necessary.
00871 
00872         o If member area creation is disabled, return None.
00873 
00874         o 'member_id', if passed, is the ID of the member whose folder is
00875           to be created;  if not passed, default to the authenticated member.
00876 
00877         o Permission:  Public # XXX?
00878         """
00879 
00880     def deleteMemberArea(member_id):
00881         """ Delete member area of specified member
00882 
00883         o Return True if a member area previously existed for the member.
00884 
00885         o 'member_id' identifies the member whose member is to be removed.
00886 
00887         o Permission:  Manage users
00888         """
00889 
00890 
00891 #
00892 #   Metadata tool interface
00893 #
00894 class IMetadataTool(Interface):
00895 
00896     """ CMF metadata policies interface.
00897     """
00898 
00899     id = Attribute('id',
00900             """ The tool's ID.
00901 
00902             o Must be set to 'portal_metadata'.
00903             """)
00904 
00905     id = Attribute('id', 'Must be set to "portal_metadata"')
00906 
00907     #
00908     #   Site-wide queries, specific to Dublin Core metadata.
00909     #
00910     def getFullName(userid):
00911         """ Convert an internal userid to a "formal" name.
00912         
00913         o Convert only if possible, perhaps using the 'portal_membership'
00914           tool;  otherwise, return 'userid'.
00915 
00916         o Used to map userid's for Creator, Contributor DCMI queries.
00917         """
00918 
00919     def getPublisher():
00920         """ Return the "formal" name of the publisher of the site.
00921         """
00922 
00923     #
00924     #   Content-specific queries, for Dublin Core metadata.
00925     #
00926     def listAllowedSubjects(content=None, content_type=None):
00927         """ List the allowed values of the 'Subject' DCMI element.
00928 
00929         o 'Subject' elements should be keywords categorizing their resource.
00930 
00931         o Return only values appropriate for content's type, or all values if
00932           both 'content' and 'content_type' are None.
00933         """
00934 
00935     def listAllowedFormats(content=None, content_type=None):
00936         """ List the allowed values of the 'Format' DCMI element.
00937 
00938         o These items should be usable as HTTP 'Content-type' values.
00939 
00940         o Return only values appropriate for content's type, or all values if
00941           both 'content' and 'content_type' are None.
00942         """
00943 
00944     def listAllowedLanguages(content=None, content_type=None):
00945         """ List the allowed values of the 'Language' DCMI element.
00946 
00947         o 'Language' element values should be suitable for generating
00948           HTTP headers.
00949 
00950         o Return only values appropriate for content's type, or all values if
00951           both 'content' and 'content_type' are None.
00952         """
00953 
00954     def listAllowedRights(content=None, content_type=None):
00955         """ List the allowed values of the 'Rights' DCMI element.
00956 
00957         o The 'Rights' element describes copyright or other IP declarations
00958           pertaining to a resource.
00959 
00960         o Return only values appropriate for content's type, or all values if
00961           both 'content' and 'content_type' are None.
00962         """
00963 
00964     #
00965     #   Content-specific queries, for generic metadata.
00966     #
00967     def listAllowedVocabulary( schema
00968                              , element
00969                              , content=None
00970                              , content_type=None
00971                              ):
00972         """ List allowed values for a given schema element and content object.
00973         
00974         o List possible keywords if both 'content' and 'content_type' are None.
00975         """
00976 
00977     #
00978     #   Schema manipulation
00979     #
00980     def listSchemas():
00981         """ Return a list of (id, schema) tuples enumerating our schema.
00982         """
00983 
00984     def addSchema( schema_id ):
00985         """ Create a new schema with the given ID.
00986 
00987         o Return the newly-created schema object.
00988 
00989         o Raise KeyError if such a schema already exists.
00990         """
00991 
00992     def removeSchema( schema_id ):
00993         """ Remove an existing schema with the given ID.
00994 
00995         o Raise KeyError if no such schema exists.
00996         """
00997 
00998     #
00999     #   Validation policy hooks.
01000     #
01001     def setInitialMetadata(content):
01002         """ Set initial values for content metatdata.
01003         
01004         o Supply any site-specific defaults.
01005         """
01006 
01007     def validateMetadata(content):
01008         """ Enforce portal-wide policies about metadata.
01009         
01010         o E.g., policies may require non-empty title/description, etc.
01011         
01012         o This method may be called by view / workflow code at "appropriate"
01013           times, such as immediately before saving changes to the metadata of
01014           an object.
01015         """
01016 
01017 
01018 #
01019 #   Site Properties tool interface
01020 #
01021 class IPropertiesTool(Interface):
01022 
01023     """ Manage properties of the site as a whole.
01024     """
01025 
01026     id = Attribute('id',
01027             """ The tool's ID.
01028 
01029             o BBB:  for use in 'getToolByName';  in the future, prefer
01030               'zapi.getUtility(IPropertiesTool)'.
01031 
01032             o Must be set to 'portal_properties'.
01033             """)
01034 
01035     def editProperties(props):
01036         """ Change portal settings.
01037 
01038         o 'props' is a mapping of values to be updates.
01039 
01040         o Permission:  Manage portal
01041         """
01042 
01043     def title():
01044         """ Return the site's title.
01045         """
01046 
01047     def smtp_server():
01048         """ Return the configured SMTP server for the site.
01049         """
01050 
01051 
01052 #
01053 #   Registration tool interface
01054 #
01055 class IRegistrationTool(Interface):
01056 
01057     """ Manage policies for member registration.
01058 
01059     o Depends on IMembershipTool component.
01060 
01061     o Is not aware of membership storage details.
01062     """
01063 
01064     id = Attribute('id',
01065             """ The ID of the tool.
01066 
01067             o Must be set to "portal_registration"
01068             """,
01069             )
01070 
01071     def isRegistrationAllowed(REQUEST):
01072         """ Return True if the current user is allowed to add a member to
01073             the site, else False.
01074 
01075         o Permission:  Public
01076         """
01077 
01078     def testPasswordValidity(password, confirm=None):
01079         """ Return None if the password is valid;  otherwise return a string
01080             explaining why not.
01081 
01082         o 'password' is the candidate password string.
01083 
01084         o If 'confirm' is passed, XXX?
01085 
01086         o Permission:  Public
01087         """
01088 
01089     def testPropertiesValidity(new_properties, member=None):
01090         """ Return None if the supplied properties are valid;  otherwise
01091             return a string explaining why not.
01092 
01093         o 'new_properties' is a mapping containing the properties to test.
01094 
01095         o 'member', if passed, is the ID of the member for whome the
01096           properties are being set;  if not passed, use the currently-
01097           authenticated member.
01098 
01099         o Permission:  Public
01100         """
01101 
01102     def generatePassword():
01103         """ Return a generated password which is complies with the site's
01104             password policy.
01105 
01106         o Permission:  Public
01107         """
01108 
01109     def addMember(id, password, roles=('Member',), domains='',
01110                   properties=None):
01111         """ Creates and return a new member.
01112 
01113         o 'id' is the user ID of the member to be created;  raise ValueError
01114           if there already exists a member with the given 'id'.
01115 
01116         o 'password' is the user's password;  raise ValueError if the
01117           supplied 'password' does not comply with the site's password policy.
01118 
01119         o 'roles' is a list of roles to grant the new member;  raise
01120           Unauthorized if the currently-authenticated user is not
01121           allowed to grant one of the roles listed
01122 
01123           - "Member" is a special role that can always be granted
01124 
01125         o 'properties', if passed,  is a mapping with additional member
01126           properties;  raise ValueError if one or more properties do not
01127           comply with the site's policies.
01128 
01129         o Permission:  Add portal member
01130         """
01131 
01132     def isMemberIdAllowed(id):
01133         """ Return True if 'id' is not in use as a member ID and is not
01134             reserved, else False.
01135 
01136         o Permission:  Add portal member
01137         """
01138 
01139     def afterAdd(member, id, password, properties):
01140         """ Notification called by portal_registration.addMember() after a
01141             member has been added successfully.
01142 
01143         o Permission:  Private (Python only)
01144         """
01145 
01146     def mailPassword(forgotten_userid, REQUEST):
01147         """ Email a forgotten password to a member.
01148 
01149         o Raise ValueError if user ID is not found.
01150 
01151         o XXX: should probably *not* raise, in order to prevent cracking.
01152 
01153         o Permission:  Mail forgotten password
01154         """
01155 
01156 
01157 #
01158 #   Skins tool interfaces
01159 #
01160 class IDirectoryView(Interface):
01161 
01162     """ Directory views mount filesystem directories.
01163     """
01164 
01165 
01166 class ISkinsContainer(Interface):
01167 
01168     """ An object that provides skins.
01169     """
01170     def getSkinPath(name):
01171         """ Convert a skin name to a skin path.
01172 
01173         o Permission:  Access contents information
01174         """
01175 
01176     def getDefaultSkin():
01177         """ Return the default skin name.
01178 
01179         o Permission:  Access contents information
01180         """
01181 
01182     def getRequestVarname():
01183         """ Return the variable name to look for in the REQUEST.
01184 
01185         o Permission:  Access contents information
01186         """
01187 
01188     def getSkinByPath(path, raise_exc=0):
01189         """ Return a skin at the given path.
01190 
01191         o XXX:  what are we doing here?
01192 
01193         o A skin path is a search path of layers of the format:
01194           'some/path, some/other/path, ...'.
01195 
01196         o Attributes are looked up in the layers in the named order.
01197 
01198         o A skin is a specially wrapped object that looks through the layers
01199           in the correct order.
01200 
01201         o Permission:  Private (Python only)
01202         """
01203 
01204     def getSkinByName(name):
01205         """ Get the named skin.
01206 
01207         Permission:  Private (Python only)
01208         """
01209 
01210 
01211 class ISkinsTool(ISkinsContainer):
01212 
01213     """ An object that provides skins to a portal object.
01214 
01215     O XXX:  This shouldn't derive from ISkinsContainer?
01216     """
01217 
01218     id = Attribute('id',
01219             """ The ID of the tool.
01220 
01221             o Must be set to "portal_skind"
01222             """,
01223             )
01224 
01225     def getSkinSelections():
01226         """ Get the sorted list of available skin names.
01227 
01228         o Permission:  Public
01229         """
01230 
01231 #
01232 # Syndication tool interface
01233 #
01234 class ISyndicationTool(Interface):
01235 
01236     """ An object that provides content syndication facilities
01237     """
01238 
01239     id = Attribute('id',
01240             """ The ID of the tool.
01241 
01242             o BBB:  for use in 'getToolByName';  in the future, prefer
01243               'zapi.getUtility(ISyndicationTool)'.
01244 
01245             o Must be set to "portal_syndication"
01246             """,
01247             )
01248 
01249     def enableSyndication(obj):
01250         """ Enable syndication for the passed-in object
01251 
01252         o raises 'Syndication is Disabled' if syndication is now allowed
01253 
01254         o raises 'Syndication Information Exists' if used repeatedly
01255         """
01256 
01257     def disableSyndication(obj):
01258         """ Disable syndication for the passed-in object
01259 
01260         o raises 'This object does not have Syndication Information' if 
01261           syndication has already been disabled
01262         """
01263 
01264     def getSyndicatableContent(obj):
01265         """ Retrieve all syndicatable content from the passed-in object
01266 
01267         o will call the hool "synContentValues" if it exists to allow
01268           individual customization
01269 
01270         o falls back to calling contentValues
01271         """
01272 
01273     def isSiteSyndicationAllowed():
01274         """ Return the site-wide syndication flag
01275         """
01276 
01277     def isSyndicationAllowed(obj=None):
01278         """ Return the syndication flag for the passed-in object
01279 
01280         o falls back to retrieving the site-wide syndication flag
01281         """
01282 
01283     def getUpdatePeriod(obj=None):
01284         """ Return the update period for the syndicated feed
01285 
01286         o falls back to the site-wide value if no object is passed in
01287 
01288         o raises 'Syndication is not Allowed' if the site-wide policy
01289           does not allow syndication
01290         """
01291 
01292     def getUpdateFrequency(obj=None):
01293         """ Return the syndicated feed update frequency
01294 
01295         o falls back to the site-wide value if no object is passed in
01296 
01297         o raises 'Syndication is not Allowed' if the site-wide policy
01298           does not allow syndication
01299         """
01300 
01301     def getUpdateBase(obj=None):
01302         """ Return the syndication feed base date for the publishing schedule
01303 
01304         o falls back to the site-wide value if no object is passed in
01305 
01306         o raises 'Syndication is not Allowed' if the site-wide policy
01307           does not allow syndication
01308         """
01309 
01310     def getHTML4UpdateBase(obj=None):
01311         """ return the HTML-formatted feed publishing base date
01312 
01313         o falls back to the site-wide value if no object is passed in
01314 
01315         o raises 'Syndication is not Allowed' if the site-wide policy
01316           does not allow syndication
01317         """
01318         
01319     def getMaxItems(obj=None):
01320         """ Return the number of items published at any one time in the feed
01321 
01322         o falls back to the site-wide value if no object is passed in
01323 
01324         o raises 'Syndication is not Allowed' if the site-wide policy
01325           does not allow syndication
01326         """
01327 
01328 #
01329 #   Types tool interfaces
01330 #
01331 class ITypeInformation(Interface):
01332 
01333     """ Type definition interface.
01334     """
01335 
01336     def Metatype():
01337         """ Return the Zope 'meta_type' for this content object.
01338 
01339         o Deprecated (not all objects of a given type may even share
01340           the same meta_type).
01341         """
01342 
01343     def Title():
01344         """ Return the "human readable" type name
01345 
01346         o Note that it may not map exactly to the 'meta_type', e.g.,
01347           for l10n/i18n or where a single content class is being
01348           used twice, under different names.
01349         """
01350 
01351     def Description():
01352         """ Return a textual description of the type
01353 
01354         o This descriptoin is used for display in a "constructor list".
01355         """
01356 
01357     def isConstructionAllowed(container):
01358         """ Return True if the current user is allowed to construct an
01359             instance of this type in 'container, else False.
01360         """
01361 
01362     def allowType(contentType):
01363         """ Can objects of 'contentType' be added to containers of our type?
01364         """
01365 
01366     def constructInstance(container, id):
01367         """ Build a "bare" instance of the appropriate type in 'container'.
01368 
01369         o Give the new instance an ID of 'id'.
01370 
01371         o Return the newly-created instance, seated in 'container'.
01372         """
01373 
01374     def allowDiscussion():
01375         """ Return True if objects of this type are allowed to support
01376             discussion, else False.
01377 
01378         o Individual objects may still disable discussion.
01379         """
01380 
01381     def getIcon():
01382         """ Return the portal-relative URL for the icon for this type.
01383         """
01384 
01385     def getMethodAliases():
01386         """ Return a mapping of method aliases for this type.
01387 
01388         o XXX:  define keys and values of the mapping.
01389 
01390         o Permission:  Manage portal
01391         """
01392 
01393     def setMethodAliases(aliases):
01394         """ Assign method aliases for this type.
01395 
01396         o Return True if the operation changed any aliases, else False.
01397 
01398         o 'aliases' is the mapping of aliases to be assigned.
01399 
01400         o XXX:  define keys and values of the mapping.
01401 
01402         o Permission:  Manage portal
01403         """
01404 
01405     def queryMethodID(alias, default=None, context=None):
01406         """ Return the method ID for a given alias.
01407 
01408         o 'context', if passed, points to the object calling this method.
01409            It may be used to return dynamic values based on the caller.
01410            XXX:  this is unclear
01411 
01412         o 'default' is returned if no such alias is defined.
01413 
01414         o Permission:  Public
01415 
01416         Returns:  Method ID or default value
01417         """
01418 
01419 
01420 class ITypesTool(Interface):
01421 
01422     """ Register content types for the site.
01423     """
01424 
01425     id = Attribute('id',
01426             """ The ID of the tool.
01427 
01428             o Must be set to "portal_types"
01429             """,
01430             )
01431 
01432     def getTypeInfo(contentType):
01433         """ Return an ITypeInformation for the given type name / object.
01434 
01435         o If 'contentType' is actually an object, rather than a string,
01436           attempt to look up the appropriate type info using its 'portal_type'.
01437 
01438         o Permission:  Public
01439         """
01440 
01441     def listTypeInfo(container=None):
01442         """ Return a sequence of ITypeInformations registered for the
01443             site.
01444 
01445         o If 'container' is passed, filter the list according to the user's
01446           permissions to add content in that place.
01447 
01448         o Permission:  Public
01449         """
01450 
01451     def listContentTypes(container=None, by_metatype=0):
01452         """ Return a sequence of IDs of ITypeInformations registered
01453             for the site.
01454 
01455         o If 'by_metatype' is True, return meta_types instead (this variant
01456           is deprecated).
01457 
01458         o If 'container' is passed, filter the list according to the user's
01459           permissions to add content in that place.
01460 
01461         o Permission:  Public
01462         """
01463 
01464     def constructContent(contentType, container, id, RESPONSE=None,
01465                          *args, **kw):
01466         """ Build an instance of the appropriate type in 'container'
01467 
01468         o 'contentType' is the name of the ITypeInformation to be
01469           constructed.
01470 
01471         o Assign the instance the given 'id', if possible.
01472 
01473         o If 'RESPONSE' is passed, redirect to the new object's
01474           "initial view";  otherwise return the new object's 'id' (which
01475           may have morphed during construction).
01476 
01477         o Raise Unauthorized if the current user is not allowed to construct
01478           items of the given type in 'container'.
01479         """
01480 
01481 
01482 #
01483 #   Undo tool interface
01484 #
01485 class IUndoTool(Interface):
01486 
01487     """ Provide access to Zope undo functions.
01488     """
01489 
01490     id = Attribute('id',
01491             """ The ID of the tool.
01492 
01493             o BBB:  for use in 'getToolByName';  in the future, prefer
01494               'zapi.getUtility(IUndoTool)'.
01495 
01496             o Must be set to "portal_undo"
01497             """,
01498             )
01499 
01500     def listUndoableTransactionsFor(object,
01501                                     first_transaction=None,
01502                                     last_transaction=None,
01503                                     PrincipiaUndoBatchSize=None):
01504         """ List all transaction IDs the user is allowed to undo on 'object'.
01505 
01506         o Return a list of "transaction info" objects, using the given
01507           parameters to batch the results.
01508 
01509         o XXX:  this needs documentation / testing.
01510 
01511         o Permission:  Undo changes
01512         """
01513 
01514     def undo(object, transaction_info):
01515         """Performs an undo operation.
01516 
01517         o Permission:  Undo changes
01518         """
01519 
01520 
01521 #
01522 #   URL tool interface
01523 #
01524 class IURLTool(Interface):
01525 
01526     """ CMF URL Tool interface.
01527 
01528     This interface provides a common mechanism for finding the 'root'
01529     object of a CMFSite, and for computing paths to objects relative to
01530     that root.
01531     """
01532 
01533     id = Attribute('id',
01534             """ The ID of the tool.
01535 
01536             o Must be set to "portal_url"
01537             """,
01538             )
01539 
01540     def __call__(relative=0, *args, **kw):
01541         """ Return URL of the site, as a string.
01542 
01543         o If 'relative' is True, return only the "path" portion of the site
01544           object's URL; otherwise, return the absolute URL
01545 
01546         o In either case, the returned path respects virtual hosting.
01547 
01548         o The site is the parent of the tool.
01549 
01550         o Permission:  Public
01551         """
01552 
01553     def getPortalObject():
01554         """ Return the site object itself.
01555 
01556         o The site is the parent of the tool.
01557 
01558         o Permission:  Public
01559         """
01560 
01561     def getRelativeContentPath(content):
01562         """ Return the site-relative path for 'content'
01563 
01564         o The site is the parent of the tool.
01565 
01566         o Return a sequence of path elements.
01567 
01568         o Permission:  Public
01569         """
01570 
01571     def getRelativeContentURL(content):
01572         """ Return the site-relative URL for 'content', as a string.
01573 
01574         o The site is the parent of the tool.
01575 
01576         o This is helpful for virtual hosting situations.
01577 
01578         o Same method as 'getRelativeURL()'
01579 
01580         o Permission:  Public
01581         """
01582 
01583     def getRelativeUrl(content):
01584         """ Return the site-relative URL for 'content', as a string.
01585 
01586         o The site is the parent of the tool.
01587 
01588         o This is helpful for virtual hosting situations.
01589 
01590         o Same method as 'getRelativeContentURL()'
01591 
01592         o Permission:  Public
01593         """
01594 
01595     def getPortalPath():
01596         """ Return the portal object's URL without the server URL component.
01597 
01598         o Return a slash-delimited string.
01599 
01600         o Permission:  Public
01601         """
01602 
01603 
01604 #
01605 #   Workflow tool interfaces
01606 #
01607 class IWorkflowTool(Interface):
01608 
01609     """This tool accesses and changes the workflow state of content.
01610     """
01611 
01612     id = Attribute('id',
01613             """ The ID of the tool.
01614 
01615             o Must be set to "portal_workflow"
01616             """,
01617             )
01618 
01619     def getCatalogVariablesFor(ob):
01620         """ Get a mapping of "workflow-relevant" attributes.
01621 
01622         o Invoked by 'portal_catalog' when indexing content.
01623 
01624         o Allows workflows to add variables to the catalog based on workflow
01625           status, making it possible to implement queues.
01626 
01627         o Permission:  Private (Python only)
01628         """
01629 
01630     def doActionFor(ob, action, wf_id=None, *args, **kw):
01631         """ Perform the given workflow action on 'ob'.
01632 
01633         o 'ob' is the target object.
01634 
01635         o 'action' is the ID of the action to perform.
01636 
01637         o 'wf_id', if passed, is the ID of the workflow supplying the action.
01638 
01639         o 'args' and 'kw', if passed, are applied to the invoked action.
01640 
01641         o Invoked by user interface code, allowing the user to request a
01642           workflow action.
01643 
01644         o The workflow object must perform its own security checks.
01645 
01646         o Permission:  Public
01647         """
01648 
01649     def getInfoFor(ob, name, default=_marker, wf_id=None):
01650         """ Get the given bit of workflow information for the object.
01651 
01652         o 'ob' is the target object.
01653 
01654         o 'name' is the name of the information requested.
01655 
01656         o 'default', if passed, will be returned if 'name' is not found;
01657           if 'default' is not passed, then raise ValueError.
01658 
01659         o 'wf_id', if passed, is the ID of the workflow supplying the action.
01660 
01661         o Invoked by user interface code, allowing the user to request
01662           information provided by the workflow.
01663 
01664         o The workflow object must perform its own security checks.
01665 
01666         o Permission:  Public
01667         """
01668 
01669     def notifyCreated(ob):
01670         """ Notify all applicable workflows that an object has been created.
01671 
01672         o 'ob' is the newly-created object;  it will already be "seated"
01673           in its new place.
01674 
01675         o Permission:  Private (Python only)
01676         """
01677 
01678     def notifyBefore(ob, action):
01679         """ Notify all applicable workflows of an action before it happens.
01680 
01681         o 'ob' is the content object which is the target of the action.
01682 
01683         o 'action' usually corresponds to a method name.
01684 
01685         o Participating workflows may veto the action by raising
01686           WorkflowException.
01687 
01688         o Unless vetoed, the tool will later call either a 'notifySuccess' or
01689           'notifyException'
01690 
01691         o Permission:  Private (Python only)
01692         """
01693 
01694     def notifySuccess(ob, action, result=None):
01695         """ Notify all applicable workflows that an action has taken place.
01696 
01697         o 'ob' is the content object which is the target of the action.
01698 
01699         o 'action' usually corresponds to a method name.
01700 
01701         o 'result' is the value returned from the action.
01702 
01703         o Permission:  Private (Python only)
01704         """
01705 
01706     def notifyException(ob, action, exc):
01707         """ Notify all applicable workflows that an action failed.
01708 
01709         o 'ob' is the content object which is the target of the action.
01710 
01711         o 'action' usually corresponds to a method name.
01712 
01713         o 'exc' is the 'sys.exec_info' triple for the exception.
01714 
01715         o Permission:  Private (Python only)
01716         """
01717 
01718     def getHistoryOf(wf_id, ob):
01719         """ Get the history of an object for a given workflow.
01720 
01721         o 'wf_id' is the id of the selected workflow.
01722 
01723         o 'ob' is the content object.
01724 
01725         o Invoked by workflow definitions.
01726 
01727         o Permission:  Private (Python only)
01728         """
01729 
01730     def getStatusOf(wf_id, ob):
01731         """ Get the last element of a workflow history for a given workflow.
01732 
01733         o 'wf_id' is the id of the selected workflow.
01734 
01735         o 'ob' is the content object.
01736 
01737         o Invoked by workflow definitions.
01738 
01739         o Permission:  Private (Python only)
01740         """
01741 
01742     def setStatusOf(wf_id, ob, status):
01743         """ Append a record to the workflow history of a given workflow.
01744 
01745         o 'wf_id' is the id of the selected workflow.
01746 
01747         o 'ob' is the content object.
01748 
01749         o 'status' is a mapping defining the history item to append.
01750 
01751         o Invoked by workflow definitions.
01752 
01753         o Permission:  Private (Python only)
01754         """
01755 
01756 
01757 class IConfigurableWorkflowTool(IWorkflowTool):
01758 
01759     """ Manage workflow tool settings.
01760     """
01761 
01762     def setDefaultChain(default_chain):
01763         """ Set the default chain for this tool.
01764 
01765         o Permission:  Manage portal
01766         """
01767 
01768     def setChainForPortalTypes(pt_names, chain, verify=True):
01769         """ Set a chain for specific portal types.
01770 
01771         o If chain is None, set the chain for the portal types to be the
01772           default chain.
01773 
01774         o Permission:  Manage portal
01775         """
01776 
01777     def getDefaultChain():
01778         """ Get the default chain for this tool.
01779 
01780         o Permission:  Private (Python only)
01781         """
01782 
01783     def listChainOverrides():
01784         """ List portal type specific chain overrides.
01785 
01786         o Permission:  Private (Python only)
01787         """
01788 
01789     def getChainFor(ob):
01790         """ Get the chain that applies to the given object.
01791 
01792         o If 'ob' is a string, it is used as portal type name.
01793 
01794         o Permission:  Private (Python only)
01795         """
01796 
01797 
01798 class IWorkflowDefinition(Interface):
01799 
01800     """Plugin interface for workflow definitions managed by IWorkflowTool.
01801     """
01802 
01803     def getCatalogVariablesFor(ob):
01804         """ Return a mapping of attributes relevant to this workflow.
01805 
01806         o Invoked by the workflow tool.
01807 
01808         o Allows workflows to add variables to the catalog based on workflow
01809           status, making it possible to implement queues.
01810 
01811         o Permission:  Private (Python only)
01812         """
01813 
01814     def updateRoleMappingsFor(ob):
01815         """ Update the object permissions according to the current workflow
01816             state of 'ob'.
01817 
01818         o Note that having the same permission(s) controlled by more than one
01819           workflow defintiion for an object results in undefined behavior.
01820 
01821         o Permission:  Private (Python only)
01822         """
01823 
01824     def listObjectActions(info):
01825         """ Return a sequence of IActionInformation defining workflow actions.
01826 
01827         o 'info' is an ObjectActionInformation structure. XXX?
01828 
01829         o Returned actions are relevant to 'info.content' (this method is
01830           called only when this workflow is applicable to 'info.content').
01831 
01832         o Invoked by the portal_workflow tool.
01833 
01834         o Permission:  Private (Python only)
01835         """
01836 
01837     def listGlobalActions(info):
01838         """ Return a sequence of IActionInformation defining workflow actions.
01839 
01840         o 'info' is an ObjectActionInformation structure. XXX?
01841 
01842         o Returned actions are "global", i.e. relevant to the user and  the
01843           site, rather than to any particular content object (this method is
01844           generally called on every request!)
01845 
01846         o Invoked by the portal_workflow tool.
01847 
01848         o Permission:  Private (Python only)
01849         """
01850 
01851     def isActionSupported(ob, action, **kw):
01852         """ Return True if the given workflow action is supported by this
01853             workfow for a content object, else False.
01854 
01855         o 'ob' is the content object.
01856 
01857         o 'action' is the ID of the requested workflow action.
01858 
01859         o Invoked by the portal_workflow tool.
01860 
01861         o Permission:  Private (Python only)
01862         """
01863 
01864     def doActionFor(ob, action, comment=''):
01865         """ Perform the requested workflow action on a content object.
01866 
01867         o 'ob' is the content object.
01868 
01869         o 'action' is the ID of the requested workflow action.
01870 
01871         o 'comment' is passed to the method corresponding to 'action'.
01872 
01873         o Invoked by the portal_workflow tool.
01874 
01875         o Allows the user to request a workflow action.
01876 
01877         o This method must perform its own security checks.
01878 
01879         o Permission:  Private (Python only)
01880         """
01881 
01882     def isInfoSupported(ob, name):
01883         """ Return True if the given info name is supported by this workflow
01884             for a given content object, else False.
01885 
01886         o 'ob' is the content object.
01887 
01888         o 'name' is the name of the requested workflow information.
01889 
01890         o Invoked by the portal_workflow tool.
01891 
01892         o Permission:  Private (Python only)
01893         """
01894 
01895     def getInfoFor(ob, name, default):
01896         """ Return the requested workflow information for a content object.
01897 
01898         o 'ob' is the content object.
01899 
01900         o 'name' is the name of the requested workflow information.
01901 
01902         o 'default' is returned if 'name' is not found.
01903 
01904         o Invoked by the portal_workflow tool.
01905 
01906         o This method must perform its own security checks.
01907 
01908         o Permission:  Private (Python only)
01909         """
01910 
01911     def notifyCreated(ob):
01912         """ Notification that an object has been created and put in its place.
01913 
01914         o 'ob' is the newly-created object.
01915 
01916         o Invoked by the portal_workflow tool.
01917 
01918         o The workflow may set initial workflow state, etc. for the new
01919           object.
01920 
01921         o Permission:  Private (Python only)
01922         """
01923 
01924     def notifyBefore(ob, action):
01925         """ Notification of a workflow action before it happens.
01926 
01927         o 'ob' is the target object of the action.
01928 
01929         o 'action' is a string identifying the impending action;
01930           usually it corresponds to a method name.
01931 
01932         o This workflow may veto by raising WorkflowException.
01933 
01934         o Unless some workflow raises WorkflowException is thrown,
01935           the workflow tool will emit either 'notifySuccess' or
01936           'notifyException' after the action.
01937 
01938         o Invoked by the portal_workflow tool.
01939 
01940         o Permission:  Private (Python only)
01941         """
01942 
01943     def notifySuccess(ob, action, result):
01944         """ Notification that a workflow action has taken place.
01945 
01946         o 'ob' is the target object of the action.
01947 
01948         o 'action' is a string identifying the succesful action;
01949           usually it corresponds to a method name.
01950 
01951         o 'result' is the return value from the method called.
01952 
01953         o Invoked by the portal_workflow tool.
01954 
01955         o Permission:  Private (Python only)
01956         """
01957 
01958     def notifyException(ob, action, exc):
01959         """ Notifies this workflow that an action failed.
01960 
01961         o 'ob' is the target object of the action.
01962 
01963         o 'action' is a string identifying the failed action;
01964           usually it corresponds to a method name.
01965 
01966         o 'exc' is the 'sys.exc_info' triple for the exception.
01967 
01968         o Invoked by the portal_workflow tool.
01969 
01970         o Permission:  Private (Python only)
01971         """