== Extension Point : ''IPropertyDiffRenderer'' ==

||'''Interface'''||''IPropertyDiffRenderer''||'''Since'''||[wiki:TracDev/ApiChanges/0.11#IPropertyDiffRenderer 0.11]||
||'''Module'''||''trac.versioncontrol.web_ui''||'''Source'''||[source:trunk/trac/versioncontrol/web_ui/changeset.py 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 [wiki:TracDev/ComponentArchitecture] and of course [wiki: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.
{{{#!python
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:
 * [source:trunk/trac/versioncontrol/web_ui/changeset.py trac.versioncontrol.web_ui.changeset.DefaultPropertyDiffRenderer][[BR]]
   Fallback for rendering multiline text as unified diffs (unless rendered by a more specific renderer).
 * [source:trunk/trac/versioncontrol/svn_prop.py trac.versioncontrol.svn_prop.SubversionMergePropertyDiffRenderer][[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.

== Additional Information and References ==

 * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.versioncontrol.web_ui.changeset.IPropertyDiffRenderer-class.html epydoc]
 * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_versioncontrol_web_ui_browser.html#trac.versioncontrol.web_ui.changeset.IPropertyDiffRenderer API Reference]
 * Related to the [[trac.versioncontrol.web_ui.browser.IPropertyRenderer]]
 * 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.)