Edgewall Software

Changes between Version 25 and Version 26 of GenshiFaq


Ignore:
Timestamp:
Oct 6, 2006, 1:16:20 AM (13 years ago)
Author:
cmlenz
Comment:

Add Q/A about custom directives

Legend:

Unmodified
Added
Removed
Modified
  • GenshiFaq

    v25 v26  
    105105 * If you are generating the snippets in question yourself, you may want to use the [wiki:ApiDocs/genshi.builder genshi.builder] to [wiki:Documentation/builder.html generate markup streams programmatically]. Just as the results of the `XML` and `HTML` functions discussed above, the stream produced using `genshi.builder` will not be escaped in the template output.
    106106
     107=== Can I add custom directives? ===
     108
     109Yes and no. Technically, it is possible to add custom directives by making a subclass of `MarkupTemplate` or `TextTemplate`. However, think twice before doing that. Genshi has been designed to get by with a standard set of generic directives; adding additional ones should not be necessary.
     110
     111Match templates provide much of the functionality you may want to get from custom directives, and are more convenient to boot. For example, let's assume you want a widget library. Instead of writing your own template directives, add an include file defining a couple match templates instead. As a simple eample, assume the following is stored a file called `widgets.html`:
     112
     113{{{
     114#!xml
     115<html xmlns="http://www.w3.org/1999/xhtml"
     116      xmlns:w="http://www.example.org/widgets"
     117      xmlns:py="http://genshi.edgewall.org/" py:strip="">
     118  <py:match path="w:pane">
     119    <div class="pane">
     120      <h4>${pane.label}</h4>
     121      ${pane.render()}
     122    </div>
     123  </py:match>
     124</html>
     125}}}
     126
     127That defines one “widget" (`<w:pane>`) that can be used in including templates as follows:
     128
     129{{{
     130#!xml
     131<html xmlns="http://www.w3.org/1999/xhtml" lang="en"
     132      xmlns:w="http://www.example.org/widgets"
     133      xmlns:xi="http://www.w3.org/2001/XInclude"
     134      xmlns:py="http://genshi.edgewall.org/">
     135  <xi:include href="widgets.html" />
     136  <py:for each="pane in panes">
     137    <w:pane data="pane" />
     138  </py:for>
     139</html>
     140}}}
     141
     142One advantage is that your using markup to define those reusable components. Another is that you're not polluting the `py:` namespace.
     143
    107144----
    108145See also: [wiki:Documentation], GenshiRecipes