Mercurial > genshi > genshi-test

annotate doc/loader.txt @ 902:09cc3627654c experimental-inline

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Sync `experimental/inline` branch with [source:trunk@1126].
author cmlenz
date Fri, 23 Apr 2010 21:08:26 +0000
parents
children
rev   line source
902
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
2
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
3 =================
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
4 Loading Templates
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
5 =================
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
6
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
7 Genshi comes with a simple but flexible implementation of a template loader in
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
8 the ``genshi.template.loader`` module. The loader provides caching of
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
9 templates so they do not need to be reparsed when used, support for multiple
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
10 template directories that together form a virtual search path, as well as
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
11 support for different template loading strategies.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
12
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
13 .. contents:: Contents
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
14 :depth: 3
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
15 .. sectnum::
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
16
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
17
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
18 -----
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
19 Usage
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
20 -----
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
21
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
22 The basic usage pattern is simple: instantiate one ``TemplateLoader`` object
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
23 and keep it around, then ask it to load a template whenever you need to load
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
24 one:
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
25
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
26 .. code-block:: python
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
27
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
28 from genshi.template import TemplateLoader
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
29
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
30 loader = TemplateLoader(['/path/to/dir1', '/path/to/dir2'],
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
31 auto_reload=True)
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
32 tmpl = loader.load('test.html')
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
33
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
34 When you try to load a template that can't be found, you get a
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
35 ``TemplateNotFound`` error.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
36
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
37 The default template class used by the loader is ``MarkupTemplate``, but that
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
38 can be overridden both with a different default (as a keyword argument to the
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
39 ``TemplateLoader`` constructor), as well as on invocation of the ``load()``
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
40 method:
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
41
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
42 .. code-block:: python
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
43
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
44 from genshi.template.text import NewTextTemplate
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
45
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
46 tmpl = loader.load('mail.txt', cls=NewTextTemplate)
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
47
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
48
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
49 -------
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
50 Caching
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
51 -------
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
52
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
53 The ``TemplateLoader`` class provides a simple in-memory cache for parsed
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
54 template objects. This improves performance, because templates do not need to
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
55 be reparsed every time they are rendered.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
56
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
57 The size of this cache can be adjusted using the `max_cache_size` option on
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
58 the ``TemplateLoader`` constructor. The value of that option determines the
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
59 maximum number of template objects kept in the cache. When this limit is
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
60 reached, any templates that haven't been used in a while get purged.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
61 Technically, this is a least-recently-used (LRU) cache, the default limit is
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
62 set to 25 templates.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
63
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
64 Automatic Reloading
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
65 ===================
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
66
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
67 Once a template has been cached, it will normally not get reparsed until it
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
68 has been purged from the cache. This means that any changes to the template
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
69 file are not taken into consideration as long as it is still found in the
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
70 cache. As this is inconvenient in development scenarios, the ``auto_reload``
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
71 option allows for automatic cache invalidation based on whether the template
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
72 source has changed.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
73
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
74 .. code-block:: python
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
75
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
76 from genshi.template import TemplateLoader
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
77
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
78 loader = TemplateLoader('templates', auto_reload=True, max_cache_size=100)
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
79
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
80 In production environments, automatic reloading should be disabled, as it does
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
81 affect performance negatively.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
82
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
83 Callback Interface
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
84 ==================
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
85
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
86 Sometimes you need to make sure that templates get properly configured after
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
87 they have been loaded, but you only want to do that when the template is
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
88 actually loaded and parsed, not when it is returned from the cache.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
89
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
90 For such cases, the ``TemplateLoader`` provides a way to specify a callback
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
91 function that gets invoked whenever a template is loaded. You can specify that
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
92 callback by passing it into the loader constructor via the ``callback``
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
93 keyword argument, or later by setting the attribute of the same name. The
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
94 callback function should expect a single argument, the template object.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
95
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
96 For example, to properly inject the `translation filter`_ into any loaded
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
97 template, you'd use code similar to this:
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
98
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
99 .. code-block:: python
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
100
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
101 from genshi.filters import Translator
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
102 from genshi.template import TemplateLoader
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
103
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
104 def template_loaded(template):
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
105 Translator(translations.ugettext).setup(template)
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
106
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
107 loader = TemplateLoader('templates', callback=template_loaded)
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
108
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
109 .. _`translation filter`: i18n.html
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
110
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
111 --------------------
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
112 Template Search Path
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
113 --------------------
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
114
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
115 The template loader can be configured with a list of multiple directories to
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
116 search for templates. The loader maps these directories to a single logical
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
117 directory for locating templates by file name.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
118
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
119 The order of the directories making up the search path is significant: the
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
120 loader will first try to locate a requested template in the first directory on
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
121 the path, then in the second, and so on. If there are two templates with the
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
122 same file name in multiple directories on the search path, whatever file is
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
123 found first gets used.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
124
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
125 Based on this design, an application could, for example, configure a search
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
126 path consisting of a directory containing the default templates, as well as a
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
127 directory where site-specific templates can be stored that will override the
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
128 default templates.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
129
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
130
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
131 Load Functions
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
132 ==============
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
133
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
134 Usually the search path consists of strings representing directory paths, but
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
135 it may also contain “load functions”: functions that are basically invoked
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
136 with the file name, and return the template content.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
137
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
138 Genshi comes with three builtin load functions:
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
139
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
140 ``directory(path)``
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
141 -------------------
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
142
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
143 The equivalent of just using a string containing the directory path: looks up
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
144 the file name in a specific directory.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
145
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
146 .. code-block:: python
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
147
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
148 from genshi.template import TemplateLoader, loader
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
149 tl = TemplateLoader([loader.directory('/path/to/dir/')])
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
150
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
151 That is the same as:
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
152
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
153 .. code-block:: python
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
154
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
155 tl = TemplateLoader(['/path/to/dir/'])
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
156
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
157
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
158 ``package(name, path)``
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
159 -----------------------
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
160
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
161 Uses the ``pkg_resources`` API to locate files in Python package data (which
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
162 may be inside a ZIP archive).
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
163
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
164 .. code-block:: python
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
165
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
166 from genshi.template import TemplateLoader, loader
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
167 tl = TemplateLoader([loader.package('myapp', 'templates')])
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
168
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
169 This will look for templates in the ``templates`` directory of the Python
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
170 package ``myapp``.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
171
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
172 ``prefixed(**delegates)``
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
173 -------------------------
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
174
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
175 Delegates load requests to different load functions based on the path prefix.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
176
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
177 .. code-block:: python
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
178
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
179 from genshi.template import TemplateLoader, loader
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
180 tl = TemplateLoader(loader.prefixed(
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
181 core = '/tmp/dir1',
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
182 plugin1 = loader.package('plugin1', 'templates'),
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
183 plugin2 = loader.package('plugin2', 'templates'),
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
184 ))
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
185 tmpl = tl.load('core/index.html')
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
186
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
187 This example sets up a loader with three delegates, under the prefixes “core”,
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
188 “plugin1”, and “plugin2”. When a template is requested, the ``prefixed`` load
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
189 function looks for a delegate with a corresponding prefix, removes the prefix
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
190 from the path and asks the delegate to load the template.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
191
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
192 In this case, assuming the directory ``/path/to/dir`` contains a file named
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
193 ``index.html``, that file will be used when we load ``core/index.html``. The
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
194 other delegates are not checked as their prefix does not match.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
195
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
196
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
197 .. note:: These builtin load functions are available both as class methods
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
198 of the ``TemplateLoader`` class as well as on the module level
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
199
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
200
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
201 Custom Load Functions
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
202 ---------------------
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
203
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
204 You can easily use your own load function with the template loader, for
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
205 example to load templates from a database. All that is needed is a callable
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
206 object that accepts a ``filename`` (a string) and returns a tuple of the form
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
207 ``(filepath, filename, fileobj, uptodate_fun)``, where:
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
208
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
209 ``filepath``
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
210 is the absolute path to the template. This is primarily used for output in
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
211 tracebacks, and does not need to map to an actual path on the file system.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
212 ``filename``
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
213 is the base name of the template file
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
214 ``fileobj``
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
215 is a readable file-like object that provides the content of the template
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
216 ``uptodate_fun``
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
217 is a function that the loader can invoke to check whether the cached version
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
218 of the template is still up-to-date, or ``None`` if the load function is not
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
219 able to provide such a check. If provided, the function should not expect
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
220 any parameters (so you'll definitely want to use a closure here), and should
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
221 return ``True`` if the template has not changed since it was last loaded.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
222
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
223 When the requested template can not be found, the function should raise an
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
224 ``IOError`` or ``TemplateNotFound`` exception.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
225
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
226
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
227 ------------------
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
228 Customized Loading
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
229 ------------------
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
230
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
231 If you require a completely different implementation of template loading, you
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
232 can extend or even replace the builtin ``TemplateLoader`` class.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
233
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
234 Protocol
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
235 ========
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
236
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
237 The protocol between the template loader and the ``Template`` class is simple
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
238 and only used for processing includes. The only required part of that protocol
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
239 is that the object assigned to ``Template.loader`` implements a ``load``
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
240 method compatible to that of the ``TemplateLoader`` class, at the minimum with
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
241 the signature ``load(filename, relative_to=None, cls=None)``.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
242
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
243 In addition, templates currently check for the existence and value of a boolean
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
244 ``auto_reload`` property. If the property does not exist or evaluates to a
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
245 non-truth value, inlining of included templates is disabled. Inlining is a
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
246 small optimization that removes some overhead in the processing of includes.
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
247
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
248 Subclassing ``TemplateLoader``
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
249 ==============================
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
250
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
251 You can also adjust the behavior of the ``TemplateLoader`` class by subclassing
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
252 it. You can of course override anything needed, but the class also provides the
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
253 ``_instantiate()`` hook, which is intended for use by subclasses to customize
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
254 the creation of the template object from the file name and content. Please
09cc3627654c Sync `experimental/inline` branch with [source:trunk@1126].
cmlenz
parents:
diff changeset
255 consult the code and the API documentation for more detail.
Copyright (C) 2012-2017 Edgewall Software