Edgewall Software

Version 1 (modified by Peter Suter, 9 years ago) ( diff )

Extension Point : ITemplateProvider

InterfaceITemplateProviderSince0.9
Moduletrac.web.chromeSourcechrome.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

trac.versioncontrol.web_ui.main.VersionControlUI provides no additional static resources and one additional directory with templates (used by other components in trac.versioncontrol): trac.versioncontrol/templates/.

import pkg_resources

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

class VersionControlUI(Component):

    implements(ITemplateProvider)
        
    # ITemplateProvider methods

    def get_htdocs_dirs(self):
        return []

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

Available Implementations

Additional Information and References

Note: See TracWiki for help on using the wiki.