Edgewall Software

Changes between Initial Version and Version 1 of TracDev/PluginDevelopment/ExtensionPoints/trac.web.chrome.ITemplateProvider


Ignore:
Timestamp:
Jun 2, 2011, 10:58:02 PM (9 years ago)
Author:
Peter Suter
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • TracDev/PluginDevelopment/ExtensionPoints/trac.web.chrome.ITemplateProvider

    v1 v1  
     1== Extension Point : ''ITemplateProvider'' ==
     2
     3||'''Interface'''||''ITemplateProvider''||'''Since'''||0.9||
     4||'''Module'''||''trac.web.chrome''||'''Source'''||[source:trunk/trac/web/chrome.py#L86 chrome.py]||
     5
     6
     7The ''ITemplateProvider'' allows components to provide their own Genshi HTML templates and static resources (like image, CSS or JavaScript files).
     8
     9== Purpose ==
     10
     11The ''ITemplateProvider'' has two purposes:
     12
     13 * 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.
     14 * 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).
     15
     16== Usage ==
     17
     18Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
     19
     20Two methods have to be defined:
     21 * {{{get_htdocs_dirs()}}} for static resource directories (if no static resource directories are required {{{return []}}})
     22   * This method is called once per request of any static resource.
     23   * 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.
     24 * {{{get_templates_dirs()}}} for template directories (if no templates directories are required {{{return []}}})
     25   * This method is called when templates are loaded / rendered by Genshi.
     26   * 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.
     27
     28Note that any files provided from package resource have to be included in setup.py of the package, e.g.:
     29{{{
     30  packages=['samplepackage'],
     31  package_data = { 'samplepackage': ['htdocs/*.js', 'htdocs/css/*.css', 'templates/*.html'] },
     32}}}
     33(See [source:trunk/setup.py#L82 setup.py] for example.)
     34
     35Most 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()}}}.
     36
     37== Examples ==
     38
     39[source:trunk/trac/versioncontrol/web_ui/main.py trac.versioncontrol.web_ui.main.VersionControlUI] provides no additional static resources and one additional directory with templates (used by other components in {{{trac.versioncontrol}}}): [source:trunk/trac/versioncontrol/templates trac.versioncontrol/templates/].
     40
     41{{{#!python
     42import pkg_resources
     43
     44from trac.core import implements, Component
     45from trac.web.chrome import ITemplateProvider
     46
     47class VersionControlUI(Component):
     48
     49    implements(ITemplateProvider)
     50       
     51    # ITemplateProvider methods
     52
     53    def get_htdocs_dirs(self):
     54        return []
     55
     56    def get_templates_dirs(self):
     57        return [pkg_resources.resource_filename('trac.versioncontrol',
     58                                                'templates')]
     59}}}
     60
     61== Available Implementations ==
     62
     63  * [source:trunk/trac/web/chrome.py#L551 trac.web.chrome.Chrome]
     64     * The main resource files and templates of Trac:
     65       * 'common' resources:
     66       * 'shared' resources:
     67       * 'site' resources:
     68       * Environment templates:
     69       * Shared templates:
     70       * Packaged templates:
     71  * The following implementations are all very similar and provide just an additional templates directory from the package respectively:
     72    * [source:trunk/trac/versioncontrol/web_ui/main.py#L24 trac.versioncontrol.web_ui.main.VersionControlUI]
     73    * [source:trunk/trac/wiki/web_ui.py#L179 trac.wiki.web_ui.WikiModule]
     74    * [source:trunk/trac/ticket/web_ui.py#L174 trac.ticket.web_ui.TicketModule]
     75    * [source:trunk/trac/timeline/web_ui.py#L255 trac.timeline.web_ui.TimelineModule]
     76    * [source:trunk/trac/search/web_ui.py#L111 trac.search.web_ui.SearchModule]
     77    * [source:trunk/trac/prefs/web_ui.py#L119 trac.prefs.web_ui.PreferencesModule]
     78    * [source:trunk/trac/admin/web_ui.py#L152 trac.admin.web_ui.AdminModule]
     79
     80== Additional Information and References ==
     81
     82 * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_web_chrome.html#trac.web.chrome.ITemplateProvider API Reference]
     83
     84 * The [http://packages.python.org/distribute/pkg_resources.html pkg_resources] module is a provided by setuptools.
     85   * [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.
     86 * For deploying static resources to be served directly by the web server see [TracIni#trac-section ''htdocs_location''].
     87   * htdocs_location ticket:  #9683
     88 * Static resource versioning ticket: #9936
     89
     90 * How to override existing templates? 
     91   * [http://article.gmane.org/gmane.comp.version-control.subversion.trac.general/9770 discussion] from 2006 when Trac still used the ClearSilver templating engine