Context Navigation

Changes between Version 46 and Version 47 of TracDev/PortingFromGenshiToJinja

Timestamp:: Feb 4, 2017, 1:03:00 PM (7 years ago)
Author:: Christian Boos
Comment:: restructure #ReplacingITemplateStreamFilter

Legend:

: Unmodified
: Added
: Removed
: Modified

TracDev/PortingFromGenshiToJinja

-              v46
+              v47
 Note that in a similar way to `Markup`, `escape` now also comes from `markupsafe`, with some slight adaptations, as `markupsafe.escape` always escapes the quotes, which is something we don't do by default. Hence always import `escape` from `trac.util.html`, never directly from `markupsafe` or Jinja2, unless you really know what you're doing.
-=== Modifying the content without 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. However, as elegant as it was, this feature was the main performance killer of Genshi, and Jinja2 doesn't propose an equivalent, for good reasons.
-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.
 ==== Produce the correct content directly instead of relying on post-processing
 There were two post-processing steps from which plugin writers did benefit, possibly unknowingly:
+There were two post-processing steps performed by Trac using Genshi stream filters from which plugin writers did benefit, possibly unknowingly:
 . the addition of the `__FORM_TOKEN` hidden parameter to <form> elements, necessary for successful POST operations
 . accessibility key enabling/disabling
 …
 For the accessibility key, it's also quite simple: instead of hard-coding the key as an `accesskey="e"` attribute, simply use the `accesskey('e')` function call, it will know if it has to produce the attribute or not depending on the current user preferences.
+==== Modify the content in the client using JavaScript
+On this day,  127/898 plugins (14.1%) on trac-hacks.org make use of `filter_stream()` from the `ITemplateStreamFilter` interface.
+=== 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. However, as elegant as it was, this feature was the main performance killer of Genshi, and Jinja2 doesn't propose an equivalent, for good reasons.
+With Jinja2, the content is produced in one step, with no possibility of post-processing. The only way left to alter the generated content is to **perform these modifications dynamically on client-side using JavaScript**.
+In February 2016, 127/898 plugins (14.1%) on trac-hacks.org made 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 we guarantee some level of support for the `ITemplateStreamFilter` during the transition period, 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.
 One strong incentive for dropping the `ITemplateStreamFilter` usage in your code is that by not doing so you basically **kill all the performance benefits** of the switch to Jinja2. The support of `ITemplateStreamFilter` implies that we first render the page to HTML using Jinja2, then parse it back as an HTML stream and feed this stream to the Genshi filter, so that it can be transformed, and then finally rendered again(!).
+One strong incentive for dropping the `ITemplateStreamFilter` usage in your code is that **by not doing so you kill all the performance benefits** brought by the switch to Jinja2. The support of `ITemplateStreamFilter` implies that we first render the page to HTML using Jinja2, then parse it back as an HTML stream and feed this stream to the Genshi filter, so that it can be transformed by these filters, and then finally rendered again(!).
 The steps for replacing `filter_stream()` are the following:
 …
 We'll discuss the specific example of the ticket [source:cboos.git/tracopt/ticket/deleter.py deleter].
+. this component already implemented `ITemplateProvider` (for providing the `ticket_delete.html` template), but the `get_htdocs_dir` didn't yet return a location. We now have to return the local `htdocs` directory, as we'll put our JavaScript file there:
+==== Implement `ITemplateProvider.get_htdocs_dirs` to be able to provide extra JavaScript code
+In our example, the component already implemented `ITemplateProvider` (for providing the `ticket_delete.html` template), but the `get_htdocs_dir` didn't yet return a location. We now have to return the local `htdocs` directory, as we'll put our JavaScript file there:
   {{{#!diff
 diff --git a/tracopt/ticket/deleter.py b/tracopt/ticket/deleter.py
 …
   Adding an `ITemplateProvider` implementation from scratch is not more complicated (if there are no templates provided by the plugin, `get_template_dirs()` can simply `return []`).
+. we need to transfer the logic at the beginning of `filter_stream()` into `post_process_request()`, i.e. the condition for which we decided to either let the content pass through unmodified or to modify it, now becomes the condition for which we decide to either add or not add our extra bit of JavaScript code.
+  So we had:
+==== Implement `IRequestFilter.post_process_request` to conditionally add JavaScript code
+We need to transfer the logic at the beginning of `filter_stream()` into `post_process_request()`, i.e. the condition for which we decided to either let the content pass through unmodified or to modify it, now becomes the condition for which we decide to either add or not add our extra bit of JavaScript code.
+So we had:
   {{{#!python
       def filter_stream(self, req, method, filename, stream, data):
 …
   }}}
   which becomes now:
+which becomes now:
   {{{#!python
       def post_process_request(self, req, template, data, content_type):
 …
   }}}
+  i.e. the condition remains the same: //the `filename`(/`template`) is either "ticket.html" or "ticket_preview.html", and we have a ticket in the `data`, that ticket exists and we have admin perm on that ticket//; if true, we would have altered the stream in `filter_stream()`, now in `post_process_request()` we'll call `add_script`.
+  Note that we also call `add_script_data`. Here we do it for some piece of session information which is not yet available in the default JavaScript data, but you'll probably have to do that for any piece of the template `data` you'll need to use in the JavaScript code. Don't pass the whole `data` dictionary though, that would be overkill and it's quite likely some bits won't convert readily to JSON. Pass only the information you'll need.
+. now the "juicy" part: do in JavaScript what the Transform filter did in Python.
+ Well, actually the //browser// needs JavaScript, but you can use whatever you want in order to produce that JavaScript code. I personally recommend using CoffeeScript as it's well suited for producing the HTML snippets we'll need.
+i.e. the condition remains the same: //the `filename`(/`template`) is either "ticket.html" or "ticket_preview.html", and we have a ticket in the `data`, that ticket exists and we have admin perm on that ticket//; if true, we would have altered the stream in `filter_stream()`, now in `post_process_request()` we'll call `add_script`.
+Note that we also call `add_script_data`. Here we do it for some piece of session information which is not yet available in the default JavaScript data, but you'll probably have to do that for any piece of the template `data` you'll need to use in the JavaScript code. Don't pass the whole `data` dictionary though, that would be overkill and it's quite likely some bits won't convert readily to JSON. Pass only the information you'll need.
+==== Modify the content in the client using JavaScript
+Now the "juicy" part: do in JavaScript what the Transform filter did in Python.
+Well, actually the //browser// needs JavaScript, but you can use whatever you want in order to produce that JavaScript code. One possibility is to use CoffeeScript as it's well suited for producing the HTML snippets we'll need.
    a. **producing the content**
       \\ \\