Changes between Initial Version and Version 1 of TracDev/PluginDevelopment/ExtensionPoints/trac.versioncontrol.web_ui.browser.IPropertyRenderer

Timestamp:

Jan 15, 2012, 3:31:54 PM (12 years ago)

Author:

Peter Suter

Comment:

—

TracDev/PluginDevelopment/ExtensionPoints/trac.versioncontrol.web_ui.browser.IPropertyRenderer

@@ +1 @@
+== Extension Point : ''IPropertyRenderer'' ==
+
+||'''Interface'''||''IPropertyRenderer''||'''Since'''||[wiki:TracDev/ApiChanges/0.11#IPropertyRenderer 0.11]||
+||'''Module'''||''trac.versioncontrol.web_ui''||'''Source'''||[source:trunk/trac/versioncontrol/web_ui/browser.py browser.py]||
+
+The ''IPropertyRenderer'' allows rendering node and changeset properties in TracBrowser and TracChangeset views.
+
+== Purpose ==
+
+Trac provides advanced source control integration with the ability to browse source code and view changesets etc. In such views it is often useful to visualize additional metadata. Trac allows arbitrary visualizations of any such data provided by the version control backend as properties.
+
+Plugins can add additional ways to render such properties by implementing !IPropertyRenderer. To render ''differences'' between properties, use [[trac.versioncontrol.web_ui.changeset.IPropertyDiffRenderer]].
+
+== Usage ==
+
+Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
+
+A class implementing !IPropertyRenderer directly can advertise variable levels of support for rendering any property in `match_property`, by matching on property `name` or `mode`.
+
+`name`: Different version control backends make different properties available, exposing metadata specific to that system. This is controlled by the [[trac.versioncontrol.api.IRepositoryConnector]] and its `Node` and `Changeset` subclasses.
+
+`mode`: By default the following values can occur, but other identifiers might be used by plugins.
+ - 'browser' rendered in the browser view
+ - 'changeset' rendered in the changeset view as a node property
+ - 'revprop' rendered in the changeset view as a revision property
+ 
+The `render_property` method is then called each time a matched property is rendered (if no other renderer matched with a higher level of support). That method should render the property, by returning:
+ - `None`: the property will be skipped
+ - an `unicode` value: the property will be displayed as text
+ - a `RenderedProperty` instance: the property will only be displayed using the instance's `content` attribute, and the other attributes will also be used in some display contexts (like `revprop`)
+ - `Markup` or other Genshi content: the property will be displayed normally, using that content as a block-level markup
+
+For rendering properties on a new kind of page call the appropriate implementation via `trac.versioncontrol.web_ui.BrowserModule(env).render_property()` or `render_properties()`.
+Usually the properties to be rendered are obtained from the `get_properties()` methods of `trac.versioncontrol.api.Changeset` or `Node` subclasses.
+
+== Examples ==
+
+The following example property renderer can be configured using a new TracIni option. All listed property names are treated as usernames, obfuscating email addresses when appropriate.
+{{{#!python
+from genshi.builder import tag
+from trac.core import *
+from trac.config import ListOption
+from trac.web.chrome import Chrome
+from trac.versioncontrol.web_ui.browser import IPropertyRenderer
+
+class UsernamePropertyRenderer(Component):
+    """Username version control property renderer."""
+
+    implements(IPropertyRenderer)
+
+    username_properties = ListOption('browser', 'username_properties',
+                                 'reviewer',
+        doc="""Comma-separated list of version control properties to render
+        as usernames (with obfuscated email address if appropriate) in the
+        repository browser.""")
+
+    def match_property(self, name, mode):
+        return 4 if name in self.username_properties
+
+    def render_property(self, name, mode, context, props):
+        username = props[name]
+        safe_username = Chrome(self.env).format_author(context.req, username)
+        return unicode(safe_username)
+}}}
+
+== Available Implementations ==
+
+In Trac:
+ * [source:trunk/trac/versioncontrol/web_ui/browser.py trac.versioncontrol.web_ui.browser.DefaultPropertyRenderer][[BR]]
+   Fallback for rendering as text any property that's not rendered by a more specific renderer.
+ * [source:trunk/trac/versioncontrol/web_ui/browser.py trac.versioncontrol.web_ui.browser.WikiPropertyRenderer][[BR]]
+   Renders [TracIni#browser-section oneliner_properties and wiki_properties] as wiki text.
+ * [source:trunk/trac/versioncontrol/svn_prop.py trac.versioncontrol.svn_prop.SubversionPropertyRenderer][[BR]]
+   Renders `svn:externals` links (translated the mapping in the[TracIni#svn:externals-section TracIni svn:externals] section.[[BR]]
+   Renders `svn:needs-lock` as a [[Image(chrome/common/lock-locked.png)]] lock icon.[[BR]]
+   Renders `svn:mergeinfo`, `svnmerge-blocked` and `svnmerge-integrated` in a simple table of merged revisions.
+ * [source:trunk/trac/versioncontrol/svn_prop.py trac.versioncontrol.svn_prop.SubversionMergePropertyRenderer][[BR]]
+   Renders `svn:mergeinfo`, `svnmerge-blocked` and `svnmerge-integrated` in a table of merged revisions, converting branch names to links and providing links to the revision log for merged and eligible revisions. (Overrides the simpler table of !SubversionPropertyRenderer.)
+
+In TracMercurial:
+ * `tracext.hg.backend.HgDefaultPropertyRenderer`[[BR]]
+   Fallback for rendering `hg-` properties that are not rendered by a more specific renderer as text.
+ * `tracext.hg.backend.CsetPropertyRenderer`[[BR]]
+   Renders `hg-Parents`, `hg-Children`, `hg-Tags` and `hg-Branch` changeset links.
+ * `tracext.hg.backend.HgExtPropertyRenderer`[[BR]]
+   Renders `hg-transplant_source` links (hg extra `transplant_source` added by the ''Transplant extension'')[[BR]]
+   Renders `hg-convert_revision` links (hg extra `convert_revision` added by the ''Convert extension'')
+
+In [th:GitPlugin]:
+ * `tracext.git.git_fs.CsetPropertyRenderer`[[BR]]
+   Renders `Parents`, `Children` and `Branches` changeset links.[[BR]]
+   Renders `git-committer` and `git-author` usernames.
+
+In [th:PerforcePlugin]:
+ * `p4trac.api.PerforcePropertyRenderer`[[BR]]
+   Renders `Tickets` links.
+    
+In [https://launchpad.net/trac-bzr Trac Bazaar Plugin]:
+ * `tracbzr.backend.BzrPropertyRenderer`[[BR]]
+   Renders `parents` changeset links and `bugs` ticket links.
+
+== Additional Information and References ==
+
+ * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.versioncontrol.web_ui.browser.IPropertyRenderer-class.html epydoc]
+ * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_versioncontrol_web_ui_browser.html#trac.versioncontrol.web_ui.browser.IWikiMacroProvider API Reference]
+ * Related to the [[trac.versioncontrol.web_ui.changeset.IPropertyDiffRenderer]]
+ * Related tickets:
+  * #1601 Initial implementation
+  * [query:keywords~=property&keywords~=properties property or properties keyword]
+  * [query:keywords=~mergeinfo mergeinfo keyword] (A set of properties used by Subversion to track merged changesets.)