Extension Point : IPropertyDiffRenderer

Interface	IPropertyDiffRenderer	Since	0.11
Module	trac.versioncontrol.web_ui	Source	changeset.py​

The IPropertyDiffRenderer allows rendering changes to 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 and its differences (diffs) between revisions. Trac allows arbitrary diff visualizations of any such data provided by the version control backend as properties.

Plugins can add additional ways to render such property diffs by implementing IPropertyDiffRenderer. To just render properties instead of property diffs, use trac.versioncontrol.web_ui.browser.IPropertyRenderer.

Usage

Implementing the interface follows the standard guidelines found in TracDev/ComponentArchitecture and of course TracDev/PluginDevelopment.

A class implementing IPropertyDiffRenderer can advertise variable levels of support for rendering any property in match_property_diff, by matching on property 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. The render_property_diff method is then called each time a matched property change is rendered (if no other renderer matched with a higher level of support). That method should render the property change, by returning:

• None: the property change will be shown the normal way (changed from old to new)
• an unicode value: the property change will be displayed as text
• Markup or other Genshi content: the property change will be displayed normally, using that content as a block-level markup

For rendering property changes on a new kind of page call the appropriate implementation via trac.versioncontrol.web_ui.changeset.ChangesetModule(env).render_property_diff(). Usually the properties to be rendered are obtained from the get_properties() method of a trac.versioncontrol.api.Node subclass.

Examples

The following example property diff renderer can be configured using a new TracIni option. All listed properties are treated as integers, calculating the numeric difference.

from trac.core import *
from trac.config import ListOption
from trac.versioncontrol.web_ui.changeset import IPropertyDiffRenderer

class IntegerPropertyDiffRenderer(Component):
    """Integer version control property diff renderer."""

    implements(IPropertyDiffRenderer)

    integer_properties = ListOption('browser', 'integer_properties',
                                    'size',
        doc="""Comma-separated list of version control properties to render
        as integers (with diff as a calculated delta) in the
        repository browser.""")

    def match_property_diff(self, name):
        return 4 if name in self.integer_properties

    def render_property_diff(self, name, old_context, old_props,
                             new_context, new_props, options):
        old_int = int(old_props[name])
        new_int = int(new_props[name])
        delta = new_int - old_int
        return unicode('Property %s increased by %+i to %i' % (name, delta,
                                                               new_int)
                       if delta > 0 else
                       'Property %s decreased by %+i to %i' % (name, delta,
                                                               new_int))

Available Implementations

In Trac:

• trac.versioncontrol.web_ui.changeset.DefaultPropertyDiffRenderer​
  Fallback for rendering multiline text as unified diffs (unless rendered by a more specific renderer).
• trac.versioncontrol.svn_prop.SubversionMergePropertyDiffRenderer
  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.

Additional Information and References

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