Context Navigation

Genshi Tutorial

This tutorial is intended to give an introduction on how to use Genshi in your web application, and present common patterns and best practices. It is aimed at developers new to Genshi as well as those who've already used Genshi, but are looking for advice or inspiration on how to improve that usage.

Introduction

In this tutorial we'll create a simple Python web application based on CherryPy 3. CherryPy was chosen because it provides a convenient level of abstraction over raw CGI or WSGI development, but is less ambitious than full-stack web frameworks such as Pylons or Django, which tend to come with a preferred templating language, and often show significant bias towards that language.

The application is a stripped-down version of sites such as reddit or digg: it lets users submit links to online articles they find interesting, and then lets other users vote on those stories and post comments. Just for kicks, we'll call that application Geddit

The project is kept as simple as possible, while still showing many of Genshi features and how to best use them:

For persistence, we'll use native Python object serialization (via the pickle module), instead of an SQL database and an ORM.

There's no authentication of any kind. Anyone can submit links, anyone can comment.

You should see a log message pointing you to the URL where the application is being served, which is usually http://localhost:8080/. Visiting that page will respond with just the string “Geddit”, as that's what the index() method of the Root object returns.

Note that we've configured CherryPy to serve static files from the geddit/static directory. CherryPy will complain that that directory does not exist, so create it, but leave it empty for now. We'll add static resources later on in the tutorial.

Basic Template Rendering

So far the code doesn't actually use Genshi, or even any kind of templating. Let's change that.

Inside of the geddit directory, create a directory called templates, and inside that directory create a file called index.html, with the following content:

This is basically an almost static HTML file with some simple variable substitution.

We now need to change the controller code so that this template is used. First, add the Genshi TemplateLoader to the imports at the top of the genshi/controller.py file, and instantiate a loader for the geddit/templates directory:

This asks the template loader for a template named index.html, generates the output stream, and finally serializes the output to HTML. You you now reload the page in your browser, you should get back the following HTML:

Data Model

To continue, we'll need to first add some classes to define the data model the application will use. As mentioned above, we're using a simple pickle file for persistence, so all we need to do here is create a couple of very simply Python classes.

Inside the geddit directory, create a file named model.py, with the following content:

And import those classes in geddit/controllers.py, just below the other imports:

fromgeddit.modelimport Submission, Comment

Now let's add some initial content to the “database”. You'll need to stop the CherryPy server to do that. Then, in the terminal, from the tutorial directory, launch the interactive Python shell, and execute the following code:

Now, if you click on the “Submit new link” link on the start page, you should see the submission form. You can enter values in the form fields and submit the form, which will take you back to the start page, where you'll see that your link has been added to the list. Or you can click on the “Cancel” button, which will take you back to the start page, but not add a link.

Please note though that we're not performing any kind of validation on the input, and that's of course a bad thing. So let's add validation next.

Adding Form Validation

We'll use FormEncode to do the validation, but we'll keep it all fairly basic. Let's declare our form in a separate file, namely geddit/form.py, which will have the following content:

Now let's use that class in the Root.submit() method. First add the from formencode import Invalid and from geddit.form import SubmissionForm lines to the imports at the top of the file. Then, update the submit() method to match the following:

As you can tell, we now only add the submitted link to our database when validation is successful: all fields need to be filled out, and the url field needs to contain a valid URL. If the submission is valid, we proceed as before. If it is not valid, we render the submission form template again, passing it the dictionary of validation errors. Let's modify the submit.html template so that it displays those error messages:

So now, if you submit the form without enterering a title, and having entered an invalid URL, you'd see something like the following:

But there's a problem here: Note how the input values have vanished from the form! We'd have to repopulate the form manually from the data submitted so far. We could do that by adding the required value="" attributes to th text fields in the template, but Genshi provides a more elegant way: the HTMLFormFiller steam filter. Given a dictionary of values, it can automatically populate HTML forms in the template output stream.

To enable this functionality, first you'll need to add the import from genshi.filters import HTMLFormFiller to the genshi/controller.py file. Next, update the bottom lines of the Root.submit() method implementation so that they look as follows:

Now, all entered values are preserved when validation errors occur. Note that the form is populated as the template is being generated, there is no reparsing and reserialization of the output.

Factoring out the Templating

By now, we already have some repetitive code when it comes to rendering templates: both the Root.index() and the Root.submit() methods look very similar in that regard: they load a specific template, call its generate() method passing it some data, and then call the render() method of the resulting stream. As we're going to be adding more controller methods, let's factor out those things into a library module.

There's a special challenge here, though: we still want to be able to add the HTMLFormFiller or other stream filters to the template output stream, which needs to be done before that output stream is serialized. We'll use a combination of a decorator and a regular function to achieve that, which collaborate using the CherryPy thread-local context.

Create a directory called lib inside the geddit directory, and inside the lib directory create two files, named __init__.py and template.py, respectively. Leave the first one empty, and in the second one, insert the following code:

In the genshi/controller.py file, you can now remove the from genshi.template import TemplateLoader line, and also the instantiation of the TemplateLoader, as that is now done in our new library module. Of course, you'll have to import that library module instead:

There's still some duplication of code in the decorators: the need to specify the serialization method and the doctype over and over again is suboptimal, and should ideally be made configurable in a central location.

Adding a Layout Template

But there's also duplication in the template files themselves: each template has to redefine the complete header and footer, and any other “decoration” markup that we may want to apply to the complete site. Now, we could simply put those commonly used markup snippets into separate HTML files and include them in the templates where they are needed. But Genshi provides a more elegant way to apply a common structure to different templates: match templates.

Most template languages provide an inheritance mechanism to allow different templates to share some kind of common structure, such as a common header, navigation, and footer. Using this mechanism, you create a “master template” in which you declare slots that “derived templates” can fill in. The problem with this approach is that it is fairly rigid: the master needs to now which content the templates will produce, and what kind of slots need to be provided for them to stuff their content in. And derived templates need to know exactly how the master Also, a derived template is itself not a well-formed or even valid HTML file, and can not be easily previewed or edited in a WYSIWYG authoring tool.

Match templates in Genshi turn this up side down. They are conceptually similar to running an XSLT transformation over your template output: you create rules that match elements in the template output stream based on XPath patterns. Whenever there is a match, the matched content is replaced by what the match template produces. This sounds complicated in theory, but is fairly intuitive in practice, so let's look at a concrete example.

Let's create a layout template first: in the geddit/templates/ directory, add a file named layout.html, with the following content:

First, note that the root element of the template is an <html> tag. This is needed because markup templates are XML documents, and XML documents require a single root element (we also use it to attach our namespace declarations, but we just as as well do that on the nested <py:match> elements). However, because the page templates that include this file will also have <html> root elements, we add the py:strip="" directive so that this second <html> tag doesn't make it through into the output stream.

Match Template Definition

#!genshi
<py:match path="head" once="true">

Here we define the first match template. The path attribute contains the XPath pattern the specifies which elements this match template should be applied to. In this case, the XPath is very simple: it matches any element with the local name “head”, so it will be applied to the <head>...</head> element (whether it's in the XHTML namespace or not). We also add the once="true" attribute to tell Genshi that we only expect a single occurrence of the <head> element in the stream. Genshi can perform some optimizations based on this information.

Selecting Matched Content

#!genshi
<head py:attrs="select('@*')">

Inside match templates, you can use the special function select(path) to access the element that matched the pattern. Here we use that function in the py:attrs directive, which basically translates to “get all attributes defined on the matched element, and add them to this element”. So for example if your page template contained <head id="foo">, the element produced by this match template would also have the same id="foo" attribute.

This is a more complex example for selecting matched content: it fetches the text contained in the <title> element of the original <head> and prefixes it with the string “geddit: ”. But as page templates may not even contain a <title> element, we first check whether it exists, and only add the colon if it does. Thus, if the page has no title of its own, the result will be “geddit”.

#!genshi
${select('*[local-name()!="title"]')}

Finally, this is an example for using a more complex XPath pattern. This select() incantation here returns a stream that contains all child elements of the original <head>, except for those elements that have the local name “title”. If we didn't add that predicate, the output stream would contain two <title> tags, and we don't want that.

If you've done a bit of XSLT, match templates should look familiar. Otherwise, you may want to familiarize yourself with the basics of XPath 1—note though that Genshi only implements a subset of the full spec as explained in Using XPath in Genshi. And just play around with match templates; at the core, the concept is actually very simple and consistent.

Now we need to update the page templates: they no longer need the header and footer, and we'll have to include the layout.html file. For the inclusion, we add the namespace prefix for XInclude, and an xi:include element.

Let's see how the template should look now for index.html:

<htmlxmlns="http://www.w3.org/1999/xhtml"xmlns:xi="http://www.w3.org/2001/XInclude"xmlns:py="http://genshi.edgewall.org/"><xi:includehref="layout.html"/><head><title>News</title></head><body><p><ahref="/submit/">Submit new link</a></p><olpy:if="submissions"><lipy:for="submission in submissions"><ahref="${submission.url}">${submission.title}</a>
posted by ${submission.username}
at ${submission.time.strftime('%M/%d/%Y %H:%m')}</li></ol></body></html>