Edgewall Software

Extension Point : IResourceManager

InterfaceIResourceManagerSince0.11
Moduletrac.resourceSourceresource.py

A IResourceManager implementation "owns" a resource realm.

Purpose

Trac uses the concept of a resource. Prominent examples are tickets or wiki pages. These kinds of resources are called resource realms.

While 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.

Implementing IResourceManager allows plugins to introduce new resource realms and implement the following operations for resources of that realm:

  • build URLs to access the resources
  • describe the resources
  • check if the resource exists

(Note that a URL for a resource must still be handled by a IRequestHandler.)

(TracFineGrainedPermissions can allow or restrict actions on individual resources.)

Usage

Implementing the interface follows the standard guidelines found in TracDev/ComponentArchitecture and of course TracDev/PluginDevelopment.

Various utility functions exist in the trac.resource module in order to manipulate the Resource identifier objects in a generic way.

The implementation responsible for a specific realm can be retrieved using ResourceSystem(env).get_resource_manager(realm), but generally the utility functions are sufficient.

Examples

A 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.

In Trac, components are not resources. The following example implementation changes this:

from trac.core import *
from trac.ticket import model
from trac.resource import IResourceManager
from trac.util.text import shorten_line
from trac.util.translation import _


class ComponentModule(Component):

    implements(IResourceManager)
    
    # IResourceManager methods
        
    def get_resource_realms(self):
        yield 'component'

    def get_resource_url(self, resource, href, **kwargs):
        return href.admin('ticket', 'components', resource.id)

    def get_resource_description(self, resource, format='default', context=None,
                                 **kwargs):
        if format == 'compact':
            return resource.id
        desc = _('Component %(name)s', name=resource.id)
        if format == 'summary':
            comp = model.Component(self.env, resource.id)
            if comp.owner:
                desc += _(' (by %(owner)s)', owner=comp.owner)
            if comp.description:
                desc += ': %s' % shorten_line(comp.description)
        return desc

    def resource_exists(self, resource):
        return bool(self.env.db_query("""
                    SELECT name FROM component WHERE name=%s""", (resource.id,)))

Available Implementations

In Trac:

AttachmentModule realm attachment
TicketSystem realm ticket
MilestoneModule realm milestone
RepositoryManager realms changeset, source and repository
WikiSystem realm wiki

In Bitten:

BuildSystem realm build

In third-party plugins:

th:FullBlogPlugin realm blog
th:TagsPlugin realm tag
th:DiscussionPlugin realm discussion
th:DownloadsPlugin realm downloads
th:TracPastePlugin realm pastebin
th:TracFormsPlugin realm forms

Additional Information and References

Last modified 7 years ago Last modified on Aug 21, 2011, 10:33:43 PM
Note: See TracWiki for help on using the wiki.