Back to index

plone3  3.1.7
_content.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 content interfaces.
00014 
00015 $Id: _content.py 77186 2007-06-28 19:06:19Z yuppie $
00016 """
00017 
00018 from zope.interface import Interface
00019 
00020 
00021 #
00022 #   Contentish interface
00023 #
00024 class IContentish(Interface):
00025 
00026     """ General interface for "contentish" items.
00027 
00028     o These methods need to be implemented by any class that wants to be a
00029       first-class citizen in the CMF world.
00030 
00031     o CMFCore.PortalContent implements this interface.
00032     """
00033 
00034     def SearchableText():
00035         """ Return a string containing textual information about the content.
00036 
00037         o This string may be the content of a file, or may be synthesized
00038           by concatenating the string attributes of the instance.
00039 
00040         o Permissions:  View
00041         """
00042 
00043 
00044 #
00045 #   Discussable interfaces
00046 #
00047 class IDiscussable(Interface):
00048 
00049     """ Interface for things which can have responses.
00050     """
00051 
00052     def createReply(title, text, Creator=None):
00053         """ Create a reply in the proper place.
00054 
00055         o Returns: HTML (directly or via redirect) # XXX
00056 
00057         o Permission: Reply to item
00058         """
00059 
00060     def getReplies():
00061         """ Return a sequence of IDiscussionResponse objects which are
00062             replies to this IDiscussable
00063 
00064         o Permission: View
00065         """
00066 
00067     def quotedContents():
00068         """ Return this object's contents in a form suitable for inclusion
00069             as a quote in a response.
00070 
00071         o The default implementation returns an empty string.  It might be
00072            overridden to return a '>' quoted version of the item.
00073 
00074         o Permission: Reply to item
00075         """
00076 
00077     def _getReplyResults():
00078         """ Return the ZCatalog results that represent this object's replies.
00079 
00080         o XXX: Huh?
00081 
00082         o Often, the actual objects are not needed.  This is less expensive
00083           than fetching the objects.
00084 
00085         o Permission: View
00086         """
00087 
00088 
00089 class IOldstyleDiscussable(Interface):
00090 
00091     """ Oldstyle discussable interface.
00092     """
00093 
00094     def createReply(title, text, REQUEST, RESPONSE):
00095         """ Create a reply in the proper place.
00096 
00097         o Returns: HTML (directly or via redirect) # XXX
00098 
00099         o Permission: Reply to item
00100         """
00101 
00102     def getReplyLocationAndID(REQUEST):
00103         """
00104         This method determines where a user's reply should be stored, and
00105         what it's ID should be.
00106 
00107         You don't really want to force users to have to select a
00108         unique ID each time they want to reply to something.  The
00109         present implementation selects a folder in the Member's home
00110         folder called 'Correspondence' (creating it if it is missing)
00111         and finds a free ID in that folder.
00112 
00113         createReply should use this method to determine what the reply
00114         it creates should be called, and where it should be placed.
00115 
00116         This method (and createReply, I expect) do not really belong in
00117         this interface.  There should be a DiscussionManager singleton
00118         (probably the portal object itself) which handles this.
00119 
00120         Permissions: None assigned
00121         Returns: 2-tuple, containing the container object, and a string ID.
00122         """
00123 
00124     def getReplyResults():
00125         """
00126         Return the ZCatalog results that represent this object's replies.
00127 
00128         Often, the actual objects are not needed.  This is less expensive
00129         than fetching the objects.
00130 
00131         Permissions: View
00132         Returns: sequence of ZCatalog results representing DiscussionResponses
00133         """
00134 
00135     def getReplies():
00136         """
00137         Return a sequence of the DiscussionResponse objects which are
00138         associated with this Discussable
00139 
00140         Permissions: View
00141         Returns: sequence of DiscussionResponses
00142         """
00143 
00144     def quotedContents():
00145         """
00146         Return this object's contents in a form suitable for inclusion
00147         as a quote in a response.  The default implementation returns
00148         an empty string.  It might be overridden to return a '>' quoted
00149         version of the item.
00150         """
00151 
00152 
00153 class IDiscussionResponse(Interface):
00154 
00155     """ Interface for objects which are replies to IDiscussable objects.
00156     """
00157 
00158     def inReplyTo(REQUEST=None):
00159         """ Return the IDiscussable object to which this item is a reply.
00160 
00161         o Permission: None assigned
00162         """
00163 
00164     def setReplyTo(reply_to):
00165         """ Make this object a response to the passed object.
00166 
00167         o 'reply_to' is an IDiscussable, or a path (as a string) to one.
00168 
00169         o Raise ValueError if 'reply_to' is not an IDiscussable (or doesn't
00170           resolve to one as a path).
00171 
00172         o XXX This does not seem like the right exception.
00173 
00174         o Permission: None assigned
00175         """
00176 
00177     def parentsInThread(size=0):
00178         """ Return a sequence of IDiscussables which are this object's parents,
00179             from the point of view of the threaded discussion.
00180 
00181         o Parents are ordered oldest to newest.
00182 
00183         o If 'size' is not zero, only the closest 'size' parents will be
00184           returned.
00185         """
00186 
00187 
00188 #
00189 #   DublinCore interfaces
00190 #
00191 class IMinimalDublinCore(Interface):
00192 
00193     """ Minimal set of Dublin Core metadata elements.
00194     """
00195 
00196     def Title():
00197         """ Return a single string, the DCMI Title element (resource name).
00198 
00199         o Permission:  View
00200         """
00201 
00202     def Description():
00203         """ Return the DCMI Description element (resource summary).
00204 
00205         o Result is a natural language description of this object.
00206 
00207         o Permission:  View
00208         """
00209 
00210     def Type():
00211         """ Return the DCMI Type element (resource type).
00212 
00213         o Result a human-readable type name for the resource (typically
00214           the Title of its type info object).
00215 
00216         o Permission:  View
00217         """
00218 
00219 
00220 class IDublinCore(IMinimalDublinCore):
00221 
00222     """ Dublin Core metadata elements supported by CMF and their semantics.
00223     """
00224 
00225     def listCreators():
00226         """ Return a sequence of DCMI Creator elements (resource authors).
00227 
00228         o Depending on the implementation, this returns the full name(s) of the
00229           author(s) of the content object or their ids.
00230 
00231         o Permission:  View
00232         """
00233 
00234     def Creator():
00235         """ Return the first DCMI Creator element, or an empty string.
00236 
00237         o Permission:  View
00238         """
00239 
00240     def Subject():
00241         """ Return a sequence of DCMI Subject elements (resource keywords).
00242 
00243         o Result is zero or more keywords associated with the content object.
00244 
00245         o Permission:  View
00246         """
00247 
00248     def Publisher():
00249         """ Return the DCMI Publisher element (resource publisher).
00250 
00251         o Result is the full formal name of the entity or person responsible
00252           for publishing the resource.
00253 
00254         o Permission:  View
00255         """
00256 
00257     def listContributors():
00258         """ Return a sequence of DCMI Contributor elements (resource
00259             collaborators).
00260 
00261         o Return zero or more collaborators (beyond thos returned by
00262           'listCreators').
00263 
00264         o Permission:  View
00265         """
00266 
00267     def Contributors():
00268         """ Deprecated alias for 'listContributors'.
00269 
00270         o 'initial caps' names are reserved for strings.
00271         """
00272 
00273     def Date(zone=None):
00274         """ Return the DCMI Date element (default resource date).
00275 
00276         o Result is a string, formatted 'YYYY-MM-DD H24:MN:SS TZ'.
00277 
00278         o If 'zone' is 'None', return the time in the system default
00279           timezone.
00280 
00281         o Permission:  View
00282         """
00283 
00284     def CreationDate(zone=None):
00285         """ Return the DCMI Date element (date resource created).
00286 
00287         o Result is a string, formatted 'YYYY-MM-DD H24:MN:SS TZ'.
00288 
00289         o If 'zone' is 'None', return the time in the system default
00290           timezone.
00291 
00292         o Permission:  View
00293         """
00294 
00295     def EffectiveDate(zone=None):
00296         """ Return the DCMI Date element (date resource becomes effective).
00297 
00298         o Result is a string, formatted 'YYYY-MM-DD H24:MN:SS TZ', or
00299           None.
00300 
00301         o If 'zone' is 'None', return the time in the system default
00302           timezone.
00303 
00304         o Permission:  View
00305         """
00306 
00307     def ExpirationDate(zone=None):
00308         """ Return the DCMI Date element (date resource expires).
00309 
00310         o Result is a string, formatted 'YYYY-MM-DD H24:MN:SS TZ', or
00311           None.
00312 
00313         o If 'zone' is 'None', return the time in the system default
00314           timezone.
00315 
00316         o Permission:  View
00317         """
00318 
00319     def ModificationDate(zone=None):
00320         """ DCMI Date element - date resource last modified.
00321 
00322         o Result is a string, formatted 'YYYY-MM-DD H24:MN:SS TZ'.
00323 
00324         o If 'zone' is 'None', return the time in the system default
00325           timezone.
00326 
00327         o Permission:  View
00328         """
00329 
00330     def Format():
00331         """ Return the DCMI Format element (resource format).
00332 
00333         o Result is the resource's MIME type (e.g. 'text/html',
00334           'image/png', etc.).
00335 
00336         o Permission:  View
00337         """
00338 
00339     def Identifier():
00340         """ Return the DCMI Identifier element (resource ID).
00341 
00342         o Result is a unique ID (a URL) for the resource.
00343 
00344         o Permission:  View
00345         """
00346 
00347     def Language():
00348         """ DCMI Language element (resource language).
00349 
00350         o Result it the RFC language code (e.g. 'en-US', 'pt-BR') for the
00351           resource.
00352 
00353         o Permission:  View
00354         """
00355 
00356     def Rights():
00357         """ Reutrn the DCMI Rights element (resource copyright).
00358 
00359         o Return a string describing the intellectual property status, if
00360           any, of the resource.
00361 
00362         o Permission:  View
00363         """
00364 
00365 
00366 class ICatalogableDublinCore(Interface):
00367 
00368     """ Provide Zope-internal date attributes for cataloging purposes.
00369     """
00370 
00371     def created():
00372         """ Return the DateTime form of CreationDate.
00373 
00374         o Permission:  View
00375         """
00376 
00377     def effective():
00378         """ Return the DateTime form of EffectiveDate.
00379 
00380         o Permission:  View
00381         """
00382 
00383     def expires():
00384         """ Return the DateTime form of ExpirationDate.
00385 
00386         o Permission:  View
00387         """
00388 
00389     def modified():
00390         """ Return the DateTime form of ModificationDate
00391 
00392         o Permission:  View
00393         """
00394 
00395 
00396 class IMutableMinimalDublinCore(IMinimalDublinCore):
00397 
00398     """ Update interface for minimal set of mutable metadata.
00399     """
00400 
00401     def setTitle(title):
00402         """ Set DCMI Title element - resource name.
00403 
00404         o Permission:  Modify portal content
00405         """
00406 
00407     def setDescription(description):
00408         """ Set DCMI Description element - resource summary.
00409 
00410         o Permission:  Modify portal content
00411         """
00412 
00413 
00414 class IMutableDublinCore(IMutableMinimalDublinCore, IDublinCore):
00415 
00416     """ Update interface for mutable metadata.
00417     """
00418 
00419     def setCreators(creators):
00420         """ Set DCMI Creator elements - resource authors.
00421 
00422         o Permission:  Modify portal content
00423         """
00424 
00425     def setSubject(subject):
00426         """ Set DCMI Subject element - resource keywords.
00427 
00428         o Permission:  Modify portal content
00429         """
00430 
00431     def setContributors(contributors):
00432         """ Set DCMI Contributor elements - resource collaborators.
00433 
00434         o Permission:  Modify portal content
00435         """
00436 
00437     def setEffectiveDate(effective_date):
00438         """ Set DCMI Date element - date resource becomes effective.
00439 
00440         o Permission:  Modify portal content
00441         """
00442 
00443     def setExpirationDate(expiration_date):
00444         """ Set DCMI Date element - date resource expires.
00445 
00446         o Permission:  Modify portal content
00447         """
00448 
00449     def setFormat(format):
00450         """ Set DCMI Format element - resource format.
00451 
00452         o Permission:  Modify portal content
00453         """
00454 
00455     def setLanguage(language):
00456         """ Set DCMI Language element - resource language.
00457 
00458         o Permission:  Modify portal content
00459         """
00460 
00461     def setRights(rights):
00462         """ Set DCMI Rights element - resource copyright.
00463 
00464         o Permission:  Modify portal content
00465         """
00466 
00467 
00468 #
00469 #   DynamicType interfaces
00470 #
00471 class IDynamicType(Interface):
00472 
00473     """ General interface for dynamic items.
00474     """
00475 
00476     def getPortalTypeName():
00477         """ Return the name of the type information for this object.
00478 
00479         o If the object is uninitialized, return None.
00480 
00481         o Permission:  Public
00482         """
00483 
00484     def getTypeInfo():
00485         """ Return the ITypeInformation object for this object.
00486 
00487         o A shortcut to 'getTypeInfo' of portal_types.
00488 
00489         o Permission:  Public
00490         """
00491 
00492     def getActionInfo(action_chain, check_visibility=0, check_condition=0):
00493         """ Get an Action info mapping specified by a chain of actions.
00494 
00495         o A shortcut to 'getActionInfo' of the related ITypeInformation
00496           object.
00497 
00498         o Permission:  Public
00499         """
00500 
00501     def getIcon(relative_to_portal=False):
00502         """ Get the path to an object's icon.
00503 
00504         o This method is used in the 'folder_contents' view to generate an
00505           appropriate icon for the items found in the folder.
00506 
00507         o If the content item does not define an attribute named "icon"
00508           return a "default" icon path (e.g., '/misc_/dtmldoc.gif', which is
00509           the icon used for DTML Documents).
00510 
00511         o If 'relative_to_portal' is True, return only the portion of
00512           the icon's URL which finds it "within" the portal;  otherwise,
00513           return it as an absolute URL.
00514 
00515         o Permission:  Public
00516         """
00517 
00518 
00519 #
00520 #   Folderish interfaces
00521 #
00522 class IFolderish(Interface):
00523 
00524     """ General interface for "folderish" content items.
00525     """
00526 
00527     def contentItems(filter=None):
00528         """ Return a sequence of (object ID, object) tuples for
00529             IContentish and IFolderish sub-objects.
00530 
00531         o Provide a filtered view onto 'objectItems', allowing only
00532           "content space" objects to show through.
00533 
00534         o Permission:  Public (not publishable)
00535         """
00536 
00537     def contentIds(filter=None):
00538         """ Return a sequence of IDs of IContentish and IFolderish sub-objects.
00539 
00540         o Provide a filtered view onto 'objectIds', allowing only
00541           "content space" objects to show through.
00542 
00543         o Permission:  Public (not publishable)
00544 
00545         Returns -- List of object IDs
00546         """
00547 
00548     def contentValues(filter=None):
00549         """ Return a sequence of IContentish and IFolderish sub-objects.
00550 
00551         o Provide a filtered view onto 'objectValues', allowing only
00552           "content space" objects to show through.
00553 
00554         o Permission:  Public (not publishable)
00555 
00556         Returns -- List of objects
00557         """
00558 
00559     def listFolderContents(contentFilter=None):
00560         """ Return a sequence of IContentish and IFolderish sub-objects,
00561             filtered by the current user's possession of the View permission.
00562 
00563         o Hook around 'contentValues' to let 'folder_contents' be protected.
00564 
00565         o Duplicates 'skip_unauthorized' behavior of 'dtml-in'.
00566 
00567         o Permission -- List folder contents
00568         """
00569 
00570 
00571 class ISiteRoot(IFolderish):
00572 
00573     """ Marker interface for the object which serves as the root of a site.
00574     """
00575 
00576 
00577 #
00578 #   IOpaqueItems interfaces
00579 #
00580 class ICallableOpaqueItem(Interface):
00581 
00582     """ Interface for callable opaque items.
00583 
00584     o Opaque items are subelements that are contained using something that
00585       is not an ObjectManager.
00586 
00587     o On add, copy, move and delete operations, a marked opaque items
00588       'manage_afterAdd', 'manage_afterClone' and 'manage_beforeDelete'
00589       hooks get called if available. Unavailable hooks do not throw
00590       exceptions.
00591     """
00592 
00593     def __init__(obj, id):
00594         """Return the opaque item and assign it to 'obj' as attr with 'id'.
00595         """
00596 
00597     def __call__():
00598         """Return the opaque items value.
00599         """
00600 
00601     def getId():
00602         """Return the id of the opaque item.
00603         """
00604 
00605 
00606 class ICallableOpaqueItemEvents(Interface):
00607 
00608     """CMF specific events upon copying, renaming and deletion.
00609     """
00610 
00611     def manage_afterClone(item):
00612         """After clone event hook.
00613         """
00614 
00615     def manage_beforeDelete(item, container):
00616         """Before delete event hook.
00617         """
00618 
00619     def manage_afterAdd(item, container):
00620         """After add event hook.
00621         """
00622 
00623 
00624 #
00625 #   Syndicatable interface
00626 #
00627 class ISyndicatable(Interface):
00628 
00629     """ Filter content for syndication.
00630     """
00631 
00632     def synContentValues():
00633         """ Return a list of IDublinCore objects to be syndicated.
00634 
00635         o For example, 'IFolderish' containers might returns a list of
00636           recently-created or modified subobjects.
00637 
00638         o Topics might return a sequence of objects from a catalog query.
00639         """