== Extension Point : ''ITemplateProvider'' ==

||'''Interface'''||''ITemplateProvider''||'''Since'''||0.9||
||'''Module'''||''trac.web.chrome''||'''Source'''||[source:trunk/trac/web/chrome.py#L86 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 [wiki:TracDev/PluginDevelopment/ExtensionPoints/trac.web.api.IRequestHandler 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 [wiki:TracDev/ComponentArchitecture] and of course [wiki: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 [source:trunk/setup.py#L82 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.

{{{#!python
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 ==

  * [source:trunk/trac/web/chrome.py#L551 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:
    * [source:trunk/trac/versioncontrol/web_ui/main.py#L24 trac.versioncontrol.web_ui.main.VersionControlUI]
    * [source:trunk/trac/wiki/web_ui.py#L179 trac.wiki.web_ui.WikiModule]
    * [source:trunk/trac/ticket/web_ui.py#L174 trac.ticket.web_ui.TicketModule]
    * [source:trunk/trac/timeline/web_ui.py#L255 trac.timeline.web_ui.TimelineModule]
    * [source:trunk/trac/search/web_ui.py#L111 trac.search.web_ui.SearchModule]
    * [source:trunk/trac/prefs/web_ui.py#L119 trac.prefs.web_ui.PreferencesModule]
    * [source:trunk/trac/admin/web_ui.py#L152 trac.admin.web_ui.AdminModule]

== Additional Information and References ==

 * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_web_chrome.html#trac.web.chrome.ITemplateProvider API Reference]

 * The [http://packages.python.org/distribute/pkg_resources.html pkg_resources] module is a provided by setuptools.
   * [http://packages.python.org/distribute/pkg_resources.html#resource-extraction 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 [TracIni#trac-section ''htdocs_location''].
   * htdocs_location ticket:  #9683
 * Static resource versioning ticket: #9936

 * How to override existing templates?  
   * [http://article.gmane.org/gmane.comp.version-control.subversion.trac.general/9770 discussion] from 2006 when Trac still used the ClearSilver templating engine