== Extension Point : ''IResourceManager'' ==

||'''Interface'''||''IResourceManager''||'''Since'''||[wiki:TracDev/ApiChanges/0.11#IResourceManager 0.11]||
||'''Module'''||''trac.resource''||'''Source'''||[source:trunk/trac/resource.py 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 [../trac.web.api.IRequestHandler IRequestHandler].)

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

== Usage ==

Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki: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, [TicketComponent components] are not resources. The following example implementation changes this:
{{{
#!python
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:
|| [source:trunk/trac/attachment.py AttachmentModule] || realm `attachment` ||
|| [source:trunk/trac/ticket/api.py TicketSystem] || realm `ticket` ||
|| [source:trunk/trac/ticket/roadmap.py MilestoneModule] || realm `milestone` ||
|| [source:trunk/trac/versioncontrol/api.py RepositoryManager] || realms `changeset`, `source` and `repository` ||
|| [source:trunk/trac/wiki/api.py WikiSystem] || realm `wiki` ||

In [bitten: Bitten]:
|| [bitten:source:trunk/bitten/main.py 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: [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]
 * See also [../trac.web.api.IRequestHandler IRequestHandler], [../trac.web.chrome.INavigationContributor INavigationContributor]
  * API Changes
   * [wiki:TracDev/ApiChanges/0.11#IResourceManager Introduced in 0.11]
 * Related tickets:
  * [query:status!=closed&keywords~=resource resource in keywords]