Edgewall Software
Last modified 4 months ago Last modified on Jan 22, 2012 12:02:41 PM

Extension Point : IPropertyRenderer

InterfaceIPropertyRendererSince0.11
Moduletrac.versioncontrol.web_uiSourcebrowser.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:

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