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

Timestamp:

Jun 2, 2011, 10:58:02 PM (13 years ago)

Author:

Peter Suter

Comment:

—

TracDev/PluginDevelopment/ExtensionPoints/trac.web.chrome.ITemplateProvider

@@ +1 @@
+== 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 ==
+
+[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/].
+
+{{{#!python
+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 ==
+
+  * [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