Mercurial > genshi > mirror
comparison doc/plugin.txt @ 769:3a59144a35b1 trunk
Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
author | cmlenz |
---|---|
date | Tue, 01 Jul 2008 10:35:01 +0000 |
parents | 1da8de3e5e51 |
children |
comparison
equal
deleted
inserted
replaced
768:f5d5afd2df2b | 769:3a59144a35b1 |
---|---|
20 | 20 |
21 | 21 |
22 Introduction | 22 Introduction |
23 ============ | 23 ============ |
24 | 24 |
25 Most Python web frameworks (with the notable exception of Django_) support | 25 Some Python web frameworks support a variety of different templating engines |
26 a variety of different templating engines through the `Template Engine Plugin | 26 through the `Template Engine Plugin API`_, which was first developed by the |
27 API`_, which was first developed by the Buffet_ and TurboGears_ projects. | 27 Buffet_ and TurboGears_ projects. |
28 | 28 |
29 .. _`Template Engine Plugin API`: http://docs.turbogears.org/1.0/TemplatePlugins | 29 .. _`Template Engine Plugin API`: http://docs.turbogears.org/1.0/TemplatePlugins |
30 .. _`Django`: http://www.djangoproject.com/ | |
31 .. _`Buffet`: http://projects.dowski.com/projects/buffet | 30 .. _`Buffet`: http://projects.dowski.com/projects/buffet |
32 .. _`TurboGears`: http://www.turbogears.org/ | 31 .. _`TurboGears`: http://www.turbogears.org/ |
33 | 32 |
34 Genshi supports this API out of the box, so you can use it in frameworks like | 33 Genshi supports this API out of the box, so you can use it in frameworks like |
35 TurboGears or `Pylons`_ without installing any additional packages. A small | 34 TurboGears or `Pylons`_ without installing any additional packages. A small |
70 name as explained above, you would use this to specify the "text" serialization | 69 name as explained above, you would use this to specify the "text" serialization |
71 method when you want to use a text template. Or you'd specify "xml" for the | 70 method when you want to use a text template. Or you'd specify "xml" for the |
72 format when you want to produce an Atom feed or other XML content. | 71 format when you want to produce an Atom feed or other XML content. |
73 | 72 |
74 | 73 |
74 Template Paths | |
75 -------------- | |
76 | |
77 How you specify template paths depends on whether you have a `search path`_ set | |
78 up or not. The search path is a list of directories that Genshi should load | |
79 templates from. Now when you request a template using a relative path such as | |
80 ``mytmpl.html`` or ``foo/mytmpl.html``, Genshi will look for that file in the | |
81 directories on the search path. | |
82 | |
83 For mostly historical reasons, the Genshi template engine plugin uses a | |
84 different approach when you **haven't** configured the template search path: | |
85 you now load templates using *dotted notation*, for example ``mytmpl`` or | |
86 ``foo.mytmpl``. Note how you've lost the ability to explicitly specify the | |
87 file extension: you now have to use ``.html`` for markup templates, and | |
88 ``.txt`` for text templates. | |
89 | |
90 Using the search path is recommended for a number of reasons: First, it's | |
91 the native Genshi model and is thus more robust and better supported. | |
92 Second, a search path gives you much more flexibility for organizing your | |
93 application templates. And as noted above, you aren't forced to use hardcoded | |
94 filename extensions for your template files. | |
95 | |
96 | |
75 Extra Implicit Objects | 97 Extra Implicit Objects |
76 ====================== | 98 ---------------------- |
77 | 99 |
78 The "genshi-markup" template engine plugin adds some extra functions that are | 100 The "genshi-markup" template engine plugin adds some extra functions that are |
79 made available to all templates implicitly, namely: | 101 made available to all templates implicitly, namely: |
80 | 102 |
81 ``HTML(string)`` | 103 ``HTML(string)`` |
228 enable the new syntax, or "no" to use the old syntax. | 250 enable the new syntax, or "no" to use the old syntax. |
229 | 251 |
230 In the version of Genshi, the default is to use the old syntax for | 252 In the version of Genshi, the default is to use the old syntax for |
231 backwards-compatibility, but that will change in a future release. | 253 backwards-compatibility, but that will change in a future release. |
232 | 254 |
255 .. _`search path`: | |
256 | |
233 ``genshi.search_path`` | 257 ``genshi.search_path`` |
234 ---------------------- | 258 ---------------------- |
235 A colon-separated list of file-system path names that the template loader should | 259 A colon-separated list of file-system path names that the template loader should |
236 use to search for templates. | 260 use to search for templates. |