Extension Point : IPropertyRenderer

Interface	IPropertyRenderer	Since	0.11
Module	trac.versioncontrol.web_ui	Source	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 TracDev/ComponentArchitecture and of course TracDev/PluginDevelopment.

A class implementing IPropertyRenderer 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.browser.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.

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 else 0

    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:

• trac.versioncontrol.web_ui.browser.DefaultPropertyRenderer​
  Fallback for rendering as text any property that's not rendered by a more specific renderer.
• trac.versioncontrol.web_ui.browser.WikiPropertyRenderer​
  Renders oneliner_properties and wiki_properties as wiki text.
• trac.versioncontrol.svn_prop.SubversionPropertyRenderer
  Renders svn:externals links (translated the mapping in theTracIni svn:externals section.
  Renders svn:needs-lock as a lock icon.
  Renders svn:mergeinfo, svnmerge-blocked and svnmerge-integrated in a simple table of merged revisions.
• trac.versioncontrol.svn_prop.SubversionMergePropertyRenderer
  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
  Fallback for rendering hg- properties that are not rendered by a more specific renderer as text.
• tracext.hg.backend.CsetPropertyRenderer
  Renders hg-Parents, hg-Children, hg-Tags and hg-Branch changeset links.
• tracext.hg.backend.HgExtPropertyRenderer
  Renders hg-transplant_source links (hg extra transplant_source added by the Transplant extension)
  Renders hg-convert_revision links (hg extra convert_revision added by the Convert extension)

In ​GitPlugin:

• tracext.git.git_fs.CsetPropertyRenderer
  Renders Parents, Children and Branches changeset links.
  Renders git-committer and git-author usernames.

In ​PerforcePlugin:

• p4trac.api.PerforcePropertyRenderer
  Renders Tickets links.

In ​Trac Bazaar Plugin:

• tracbzr.backend.BzrPropertyRenderer
  Renders parents changeset links and bugs ticket links.

In ​Trac Darcs Plugin:

• tracdards.components.EquivalentChangesetsRenderer
  Renders links to equivalent patches present in other repositories.
• tracdards.components.MissingInReposRenderer
  Renders a list of repositories where this changeset is missing.
• tracdards.components.HashnameRenderer
  Renders a permanent link to the changeset based on a hashname.

Additional Information and References

• ​epydoc
• ​API Reference
• Related to the trac.versioncontrol.web_ui.changeset.IPropertyDiffRenderer
• Related tickets:
  • #1601 Initial implementation
  • property or properties keyword
  • mergeinfo keyword (A set of properties used by Subversion to track merged changesets.)