Changes between Version 40 and Version 41 of TracDev/PortingFromGenshiToJinja

Timestamp:

Jan 28, 2017, 12:14:31 AM (7 years ago)

Author:

Christian Boos

Comment:

move the #Generatingcontent section before the "Modifying content" one

TracDev/PortingFromGenshiToJinja

@@ -598 +598 @@
 
 Note that as long as we have to support the legacy Genshi templates, a `None` value passed as third argument won't be interpreted as an empty `dict`, but rather as an empty `content_type`.
+
+
+
+=== Generating content
+
+==== Rendering template "fragments"
+When one wants to directly render a template, the Chrome `render_template` can still be used, as before:
+{{{#!py
+return Chrome(self.env).render_template(
+                req, 'query_results.html', data, None, fragment=True)
+}}}
+However, `render_template` prepares all the data needed to render a page in the full default layout. It also now consistently returns an output that is prepared to be sent back to the client. So if you need to embed the generated content in other generated content, this method is the best choice.
+
+`render_fragment` can be used instead. It returns a `Markup` string when generating output for the web (`text=False`) or an `unicode` string when generating plain text output (`text=True`).
+
+//See [source:cboos.git/trac/ticket/query.py@jinja2-trunk-r15379#L1423 Ticket Query] macro (''table'' mode)//
+
+When the fragment needs to be sent to the client, there's still a better choice than `render_template`, it's `generate_fragment`, as it won't impose as much overhead on the data dictionary as `render_template`. It's best suited for responding to XHRs:
+{{{#!python
+        if req.is_xhr:  # render and return the content only
+            stream = Chrome(self.env).generate_fragment(
+                req, 'changeset_content.html', data)
+            req.send(stream)
+}}}
+
+This automatically retrieves the `use_chunked_encoding` TracIni setting and uses it to return an iterable.  In any case, the returned value can be sent directly from the `Request` object.
+
+There's even a lower-level public API in `Chrome` for generating content using Jinja2 templates, which provides even greater control. 
+//See the [source:cboos.git/trac/ticket/notification.py@jinja2-trunk-r15379#L311 rendering of the ticket change notification e-mail]//
+
+See the API documentation for further details.
+
+
+==== The `tag` builder #tag
+
+Genshi provided a nice Python API for programmatically building (X)HTML elements. This consisted of the `Fragment`, `Element` and the `tag` builder, all from the `genshi.builder` module:
+{{{#!python
+from genshi import Fragment, Element, tag
+}}}
+This has now been replaced by an equivalent API which lives in `trac.util.html`, so the above import should be replaced with:
+{{{#!python
+from trac.util.html import Fragment, Element, tag
+}}}
+Note that the `html` symbol from `trac.util.html` which used to be a alias to `genshi.builder.tag` is now naturally an alias to `trac.util.html.tag`.
+
+One way to write "portable" code would be:
+{{{#!python
+from trac.util.html import html as tag
+}}}
+You can then use the `tag` builder API regardless of its origin.
+
+
+The behavior of the new `tag` builder is nearly the same as the old one,
+except that it has even more "knowledge" about the HTML format. For example, for the `class` attribute (or rather, `class_` as `class` is a reserved Python keyword), and for the `style` attribute, dicts can be given as parameters instead of plain strings. Other attributes, like `checked`, will be omitted when given a `False` value.
+
+As this special behavior could be unwanted when arbitrary XML must be generated instead of XHTML, another builder, `xml`, is now available. The `xml` builder can be used the same way as the `tag` builder, but when serialized, its only special behavior is to omit attributes which have the value `None`. 
+
+==== The `Markup` class
+
+Likewise, if you want to use the `Markup` class, you should write:
+{{{#!python
+from trac.util.html import Markup
+}}}
+In "old" versions of Trac, you'll get `genshi.core.Markup`, whereas now you'll get `markupsafe.Markup`: as we're using Jinja2, we're also making use of its direct dependency [PyPI:MarkupSafe].
+
+==== The `escape` function
+
+{{{#!python
+from trac.util.html import escape
+}}}
+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.
 
 
@@ -822 +893 @@
 See the full changeset, [bf49f871/cboos.git] (and [be0ff94a/cboos.git] for a look to the generated .js).
 
-=== Generating content
-
-==== Rendering template "fragments"
-When one wants to directly render a template, the Chrome `render_template` can still be used, as before:
-{{{#!py
-return Chrome(self.env).render_template(
-                req, 'query_results.html', data, None, fragment=True)
-}}}
-However, `render_template` prepares all the data needed to render a page in the full default layout. It also now consistently returns an output that is prepared to be sent back to the client. So if you need to embed the generated content in other generated content, this method is the best choice.
-
-`render_fragment` can be used instead. It returns a `Markup` string when generating output for the web (`text=False`) or an `unicode` string when generating plain text output (`text=True`).
-
-//See [source:cboos.git/trac/ticket/query.py@jinja2-trunk-r15379#L1423 Ticket Query] macro (''table'' mode)//
-
-When the fragment needs to be sent to the client, there's still a better choice than `render_template`, it's `generate_fragment`, as it won't impose as much overhead on the data dictionary as `render_template`. It's best suited for responding to XHRs:
-{{{#!python
-        if req.is_xhr:  # render and return the content only
-            stream = Chrome(self.env).generate_fragment(
-                req, 'changeset_content.html', data)
-            req.send(stream)
-}}}
-
-This automatically retrieves the `use_chunked_encoding` TracIni setting and uses it to return an iterable.  In any case, the returned value can be sent directly from the `Request` object.
-
-There's even a lower-level public API in `Chrome` for generating content using Jinja2 templates, which provides even greater control. 
-//See the [source:cboos.git/trac/ticket/notification.py@jinja2-trunk-r15379#L311 rendering of the ticket change notification e-mail]//
-
-See the API documentation for further details.
-
-
-==== The `tag` builder #tag
-
-Genshi provided a nice Python API for programmatically building (X)HTML elements. This consisted of the `Fragment`, `Element` and the `tag` builder, all from the `genshi.builder` module:
-{{{#!python
-from genshi import Fragment, Element, tag
-}}}
-This has now been replaced by an equivalent API which lives in `trac.util.html`, so the above import should be replaced with:
-{{{#!python
-from trac.util.html import Fragment, Element, tag
-}}}
-Note that the `html` symbol from `trac.util.html` which used to be a alias to `genshi.builder.tag` is now naturally an alias to `trac.util.html.tag`.
-
-One way to write "portable" code would be:
-{{{#!python
-from trac.util.html import html as tag
-}}}
-You can then use the `tag` builder API regardless of its origin.
-
-
-The behavior of the new `tag` builder is nearly the same as the old one,
-except that it has even more "knowledge" about the HTML format. For example, for the `class` attribute (or rather, `class_` as `class` is a reserved Python keyword), and for the `style` attribute, dicts can be given as parameters instead of plain strings. Other attributes, like `checked`, will be omitted when given a `False` value.
-
-As this special behavior could be unwanted when arbitrary XML must be generated instead of XHTML, another builder, `xml`, is now available. The `xml` builder can be used the same way as the `tag` builder, but when serialized, its only special behavior is to omit attributes which have the value `None`. 
-
-==== The `Markup` class
-
-Likewise, if you want to use the `Markup` class, you should write:
-{{{#!python
-from trac.util.html import Markup
-}}}
-In "old" versions of Trac, you'll get `genshi.core.Markup`, whereas now you'll get `markupsafe.Markup`: as we're using Jinja2, we're also making use of its direct dependency [PyPI:MarkupSafe].
-
-==== The `escape` function
-
-{{{#!python
-from trac.util.html import escape
-}}}
-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.
-
+