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

Timestamp:

Aug 21, 2011, 9:55:08 PM (13 years ago)

Author:

Peter Suter

Comment:

—

TracDev/PluginDevelopment/ExtensionPoints/trac.resource.IResourceManager

@@ +1 @@
+== 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 = _('Componment %(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]