Extension Point : ITemplateProvider

Interface	ITemplateProvider	Since	0.9
Module	trac.web.chrome	Source	chrome.py​

The ITemplateProvider allows components to provide their own Genshi HTML templates and static resources (like image, CSS or JavaScript files).

Purpose

The ITemplateProvider has two purposes:

• It allows a component to define paths to Genshi HTML templates. Any template files used e.g. by an IRequestHandler must be provided here.
• It allows a component to define paths to static resource files. Any static files that should be accessible to a user's web browser (usually because they are referenced in a used HTML template or by a call to trac.web.chrome.add_script or add_stylesheet or similar).

Usage

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

Two methods have to be defined:

• get_htdocs_dirs() for static resource directories (if no static resource directories are required return [])
  • This method is called once per request of any static resource.
  • A common implementation is to return [('prefix', pkg_resources.resource_filename('package', 'dir'))] where 'prefix' defines a prefix to the URL for these resources, 'package' is the package name and 'dir' is the name of the directory with static resource files in that package to be provided.
• get_templates_dirs() for template directories (if no templates directories are required return [])
  • This method is called when templates are loaded / rendered by Genshi.
  • A common implementation is to return [pkg_resources.resource_filename('package', 'dir')] where 'package' is the package name and 'dir' is the name of the directory with template files in that package to be provided.

Note that any files provided from package resource have to be included in setup.py of the package, e.g.:

  packages=['samplepackage'],
  package_data = { 'samplepackage': ['htdocs/*.js', 'htdocs/css/*.css', 'templates/*.html'] },

(See setup.py​ for example.)

Most likely, a component implementing this interface would also at least implement IRequestHandler, return a template or static resource directory and use names of files in these directories during process_request().

Examples

A minimal ITemplateProvider in isolation is not very useful (but possible) and usually accompanied by implementations of other interfaces that utilize the provided templates. Hence the following example is best understood in context of the ComponentModuleExamples.

In Trac, components have no associated templates (besides the admin panels). The following example provides no additional static resources, but one additional templates directory used by other components in the example trac.component package.

import pkg_resources

from trac.core import implements, Component
from trac.web.chrome import ITemplateProvider

class ComponentModule(Component):

    implements(ITemplateProvider)
        
    # ITemplateProvider methods

    def get_htdocs_dirs(self):
        return []

    def get_templates_dirs(self):
        return [pkg_resources.resource_filename('trac.component',
                                                'templates')]

Available Implementations

• trac.web.chrome.Chrome​
  • The main resource files and templates of Trac:
    • 'common' resources:
    • 'shared' resources:
    • 'site' resources:
    • Environment templates:
    • Shared templates:
    • Packaged templates:
• The following implementations are all very similar and provide just an additional templates directory from the package respectively:
  • trac.versioncontrol.web_ui.main.VersionControlUI
  • trac.wiki.web_ui.WikiModule​
  • trac.ticket.web_ui.TicketModule​
  • trac.timeline.web_ui.TimelineModule​
  • trac.search.web_ui.SearchModule​
  • trac.prefs.web_ui.PreferencesModule​
  • trac.admin.web_ui.AdminModule​

Additional Information and References

• ​API Reference

• The ​pkg_resources module is a provided by setuptools.
  • ​pkg_resources.resource_filename should extract the embedded resources to a path accessible by trac / the web server.
• For deploying static resources to be served directly by the web server see 'htdocs_location'.
  • htdocs_location ticket: #9683
• Static resource versioning ticket: #9936

• How to override existing templates?
  • ​discussion from 2006 when Trac still used the ClearSilver templating engine