== 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 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.
{{{#!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 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:
 * [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.

In [http://progetti.arstecnica.it/trac+darcs Trac Darcs Plugin]:
 * `tracdards.components.EquivalentChangesetsRenderer`[[BR]]
   Renders links to equivalent patches present in other repositories.
 * `tracdards.components.MissingInReposRenderer`[[BR]]
   Renders a list of repositories where this changeset is missing.
 * `tracdards.components.HashnameRenderer`[[BR]]
   Renders a permanent link to the changeset based on a hashname.

== 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.IPropertyRenderer 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.)