Edgewall Software

Version 4 (modified by al.willmer@…, 10 years ago) ( diff )

Spelling, tempaltes → templates

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

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

Additional Information and References

Note: See TracWiki for help on using the wiki.