Extension Point : IResourceManager

Interface	IResourceManager	Since	0.11
Module	trac.resource	Source	resource.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

• Epydoc API Reference: ​IPermissionStore, ​Resource module
• See also IRequestHandler, INavigationContributor
  • API Changes
    • Introduced in 0.11
• Related tickets:
  • resource in keywords