Changes between Version 5 and Version 6 of TracDev/PortingFromGenshiToJinja

Timestamp:

Feb 22, 2016, 10:18:31 PM (8 years ago)

Author:

Christian Boos

Comment:

#ReplacingITemplateStreamFilter, part 1, the __FORM_TOKEN input

TracDev/PortingFromGenshiToJinja

@@ -310 +310 @@
 
 
-=== Examples ===
+== Examples
 Let's first take a simple full-contained example from the Trac source, the simple index.html / jindex.html templates.
 
@@ -399 +399 @@
 == Changes in the controllers ==
 
-=== Implementing the `IRequestHandler` interface ===
+=== Implementing the `IRequestHandler` interface
 
 With Genshi, the data for the template is basically a `dict`, which has to be returned by `process_request`
 at the same time as the template name. This hasn't changed with Jinja2.
+
+In fact, no changes to the `IRequestHandler` interface were needed.
+
+
+=== Replacing the `ITemplateStreamFilter` interface #ReplacingITemplateStreamFilter 
+
+One of the strengths of Genshi was its ability to transform the normal HTML content and, for example, to inject arbitrary content at any point in the HTML, thanks to the use of the Transform stream filter and its API.
+
+With Jinja2, the content is produced in one step, with no kind of post-processing. Hence the content should either be produced right away, or if it really has to be produced as an extra step, it should be produced dynamically on client-side using JavaScript.
+
+==== Producing the correct content directly
+
+There were two post-processing steps from which plugin writers did benefit, possibly unknowingly:
+ 1. the addition of the `__FORM_TOKEN` hidden parameter to <form> elements, necessary for successful POST operations
+ 2. accessibility key enabling/disabling (TODO)
+
+As this no longer happen, it's now the responsibility of plugin writers to add this <input> in their content. This is simple enough:
+{{{#!html+jinja
+<form action="#" method="post">
+  <input type="hidden" name="__FORM_TOKEN" value="${form_token}" />
+  ...
+</form>
+}}}
+This gets even simpler thanks to a default macro:
+{{{#!html+jinja
+<form action="#" method="post">
+  ${jmacros.form_token_input()}
+  ...
+</form>
+}}}
+
+The `jmacros` corresponds to the [source:cboos.git/trac/templates/jmacros.html@jinja2 trac/templates/jmacros.html] default macros, and this file is included by default (in `jlayout.html`), so you don't have to bother to include it yourself (as most of the templates will extend `jlayout.html`).
+
+
+==== Hooking into the HTML content produced by other templates
+
+On this day,  127/898 plugins (14.1%) on trac-hacks.org make use of `filter_stream()` from the `ITemplateStreamFilter` interface. 
+
+So this means this specific step of the migration, perhaps the less straightforward, will be of interest for most plugin developers.
+
+Note that though it wouldn't harm to leave the code for `ITemplateStreamFilter` around for use by Trac < 1.4, the new suggested way also works great with earlier versions of Trac (1.0 and 1.2, perhaps even 0.12), so there's really no reason to maintain both versions once you did the switch.
+
+
+
 
 === Generating content ===