Edgewall Software

Changes between Initial Version and Version 1 of TracDev/PluginDevelopment/ExtensionPoints/trac.resource.IResourceManager


Ignore:
Timestamp:
Aug 21, 2011, 9:55:08 PM (8 years ago)
Author:
Peter Suter
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • TracDev/PluginDevelopment/ExtensionPoints/trac.resource.IResourceManager

    v1 v1  
     1== Extension Point : ''IResourceManager'' ==
     2
     3||'''Interface'''||''IResourceManager''||'''Since'''||[wiki:TracDev/ApiChanges/0.11#IResourceManager 0.11]||
     4||'''Module'''||''trac.resource''||'''Source'''||[source:trunk/trac/resource.py resource.py]||
     5
     6A ''IResourceManager'' implementation "owns" a ''resource realm''.
     7
     8== Purpose ==
     9
     10Trac uses the concept of a ''resource''. Prominent examples are tickets or wiki pages. These ''kinds'' of resources are called ''resource realms''.
     11
     12While such resources are traditionally represented by different model classes, there is also a generic `Resource` handle type that supports a few generic operations. This allows some systems to be implemented generically, instead of requiring explicit support for each resource realm.
     13
     14Implementing IResourceManager allows plugins to introduce new resource realms and implement the following operations for resources of that realm:
     15* build URLs to access the resources
     16* describe the resources
     17* check if the resource exists
     18
     19(Note that a URL for a resource must still be handled by a [../trac.web.api.IRequestHandler IRequestHandler].)
     20
     21(TracFineGrainedPermissions can allow or restrict actions on individual resources.)
     22
     23== Usage ==
     24
     25Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
     26
     27Various utility functions exist in the trac.resource module in order to manipulate the Resource identifier objects in a generic way.
     28
     29The implementation responsible for a specific realm can be retrieved using `ResourceSystem(env).get_resource_manager(realm)`, but generally the utility functions are sufficient.
     30
     31== Examples ==
     32
     33A IResourceHandler in isolation is not very useful (but possible) and usually accompanied by implementations of other interfaces. Hence the following example is best understood in context of the ComponentModuleExamples.
     34
     35In Trac, [TicketComponent components] are not resources. The following example implementation changes this:
     36{{{
     37#!python
     38from trac.core import *
     39from trac.ticket import model
     40from trac.resource import IResourceManager
     41from trac.util.text import shorten_line
     42from trac.util.translation import _
     43
     44
     45class ComponentModule(Component):
     46
     47    implements(IResourceManager)
     48   
     49    # IResourceManager methods
     50       
     51    def get_resource_realms(self):
     52        yield 'component'
     53
     54    def get_resource_url(self, resource, href, **kwargs):
     55        return href.admin('ticket', 'components', resource.id)
     56
     57    def get_resource_description(self, resource, format='default', context=None,
     58                                 **kwargs):
     59        if format == 'compact':
     60            return resource.id
     61        desc = _('Componment %(name)s', name=resource.id)
     62        if format == 'summary':
     63            comp = model.Component(self.env, resource.id)
     64            if comp.owner:
     65                desc += _(' (by %(owner)s)', owner=comp.owner)
     66            if comp.description:
     67                desc += ': %s' % shorten_line(comp.description)
     68        return desc
     69
     70    def resource_exists(self, resource):
     71        return bool(self.env.db_query("""
     72                    SELECT name FROM component WHERE name=%s""", (resource.id,)))
     73}}}
     74
     75== Available Implementations ==
     76
     77In Trac:
     78|| [source:trunk/trac/attachment.py AttachmentModule] || realm `attachment` ||
     79|| [source:trunk/trac/ticket/api.py TicketSystem] || realm `ticket` ||
     80|| [source:trunk/trac/ticket/roadmap.py MilestoneModule] || realm `milestone` ||
     81|| [source:trunk/trac/versioncontrol/api.py RepositoryManager] || realms `changeset`, `source` and `repository` ||
     82|| [source:trunk/trac/wiki/api.py WikiSystem] || realm `wiki` ||
     83
     84In [bitten: Bitten]:
     85|| [bitten:source:trunk/bitten/main.py BuildSystem] || realm `build` ||
     86
     87In third-party plugins:
     88
     89|| th:FullBlogPlugin || realm `blog` ||
     90|| th:TagsPlugin || realm `tag` ||
     91|| th:DiscussionPlugin || realm `discussion` ||
     92|| th:DownloadsPlugin || realm `downloads` ||
     93|| th:TracPastePlugin || realm `pastebin` ||
     94|| th:TracFormsPlugin || realm `forms` ||
     95
     96== Additional Information and References ==
     97
     98 * Epydoc API Reference: [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.perm.IPermissionStore-class.html IPermissionStore], [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.resource-module.html Resource module]
     99 * See also [../trac.web.api.IRequestHandler IRequestHandler], [../trac.web.chrome.INavigationContributor INavigationContributor]
     100  * API Changes
     101   * [wiki:TracDev/ApiChanges/0.11#IResourceManager Introduced in 0.11]
     102 * Related tickets:
     103  * [query:status!=closed&keywords~=resource resource in keywords]