Migrating from Genshi ====================================== FastPt uses syntax derived from the syntax of Genshi. In particular, the following directives are supported, with semantics intended to be nearly identical to those of Genshi_. * `py:def` * `py:when` * `py:otherwise` * `py:for` * `py:if` * `py:choose` * `py:with` * `py:replace` * `py:content` * `py:attrs` * `py:strip` * `xi:include` Note that, in particular, `py:match` is not supported. In addition, FastPt supports the following additional directives: * `py:include` - same semantics as `xi:include`, use if you don't like lots of namespaces in your xml * `py:extends` - indicates that this is an extension template. The parent template will be read in and used for layout, with any `py:slot` directives in the child template overriding the `py:slot` directives defined in the parent. * `py:slot` - used to name a replaceable 'slot' in a parent template, or to specify a slot override in a child template. The `py:slot` semantics are modeled after the `{% block %}` semantics of Jinja2_. * `py:super` - used to insert the contents of a parent `py:slot`, modeled after `{% super %}` in Jinja2_. Generally, migration consists of a few steps that can be simple or quite difficult based on your fondness of the `py:match` directive in Genshi. In simple cases where you have one `master.html` template with a few `py:match` directives that is `xi:included` into all your page templates, the following steps should suffice: * You may need to rewrite some of our `xi:include` directives to use FastPt's module naming system and relative imports. * In a simple case where you have only a few `py:match` directives, all of which are in a `master.html` template that is being included from child templates, I recommend that you rewrite the `master.html` as `layout.html`, defining named `py:slot` regions that will be overridden in child templates. * In your child templates, remove the `` that probably lurks near the top. Then add a `py:extends` directive to the top-level tag (usually ``). The tag the parts of the child template that are intended to override parts of the parent template with the `py:slot` directive. Example Migration ========================== Suppose you have a couple of Genshi templates, one of which called `master.html` and one of which is `index.html`. (TurboGears developers may recognize these files as slightly modified versions of the default templates deposited in a TG quickstarted project.) The contents of `master.html` are: .. literalinclude:: include/master.html :linenos: :language: html Likewise, the contents of `index.html` are as follows: .. literalinclude:: include/index.html :linenos: :language: html In order to perform our fastpt migration, we begin by creating two empty templates. The first one will replace our `master.html`, and we will call it `layout.html`: .. literalinclude:: include/layout.html :linenos: :language: html Note the introduction of the `py:slot` directive, and the disappearance of the `py:match` directives from `master.html`. `py:slot` mimics the behavior of Jinja2 "blocks", providing a name to a construct in a parent template which can be replaced by the contents of `py:slot` -named constructs in child templates. For instance, the "title" slot in `layout.html`: .. literalinclude:: include/layout.html :linenos: :language: html :lines: 10 can be replaced by a similarly-named slot in the child document `index_fastpt.html`: .. literalinclude:: include/index_fastpt.html :linenos: :language: html :lines: 1-6, 9-10 We also provide a way of including the contents of the parent template's slot in a child template's slot using ``. The following slot in `layout.html`: .. literalinclude:: include/layout.html :linenos: :language: html :lines: 18 can be replaced in `include/index_fastpt.html` with: .. literalinclude:: include/index_fastpt.html :linenos: :language: html :lines: 12-15 Yielding the following html once rendered: .. code-block:: html :linenos:

My Header

Some extra header data

.. _Genshi: http://genshi.edgewall.org/ .. _Jinja2: http://jinja.pocoo.org/2/documentation/