Email rendering with Grantlee

The GCDS videos have been online for a while now, but I thought I’d draw some attention to my talk about Grantlee for those that missed it.

Video — Slides

The demo which gets most peoples attention is the example_mail application. example_mail is a small demo application which accesses emails through Akonadi. It’s not intended to be fully functional, but currently it can read email.

I ported it to use Grantlee for the rendering of emails, which allows for theming support. That in itself is not really special, but it gets more
interesting when you consider that the Grantlee themes and images themselves are coming from Akonadi too. There is a Grantlee loader for retrieving templates from Akonadi, and an Akonadi resource for storing and handling updates Grantlee themes. Go orthongonality!

You can imagine a rollout of 10,000 workstations, with a customized theme in the KMail reader with the corporate identity of a customer, and using the right colours and logo.

If one day that company gets a new identity or is bought and rebranded, each of those workstations will need to be updated with a new theme. How do you update all of the 10,000 workstations? With Grantlee and Akonadi, you simply update the theme in one place, your groupware server, which pushes the update, and every workstation is updated instantly. I mean really instantly. No need to push a refresh button, or to select another email for it to be re-rendered with the updated theme.

The way the theming works is quite interesting (I can write about how the instant updates work another time). There is a base.html file, which describes a skeleton html file with some css style. It also has a little bit of extra markup, such as {{ messageContent|safe }}, which tells Grantlee where to put the actual text of the message, and some {% block %} tags. The {% block %} tags don’t have any effect in the base.html file except to indicate that the text between the blocks can be over-ridden. There is one block defined with some css inside it, one block above the email content called "header", and one block below called "footer".

The file template.html contains a tag at the top with the content {% extends "base.html" %}. That indicates to the Grantlee system that this file will inherit from the base.html file and override some blocks in it. Each theme file can override as many or as few blocks as they want. template.html only overrides the header block from base.html, and inserts the table you see in the first screenshot above. Images in the are represented by <img src="{% media_finder "qtlogo-2007.png" %}" /> for example. The media_finder tag is a tag which inserts a url into the rendered theme. In this case, I’m retrieving media using Akonadi, so it will be replaced by an Akonadi url, something like akonadi:item=6. There is already a plugin for retrieving themes and media from filesystem, which could be configured to use KStandardDirs. By next week, there should be a Grantlee plugin to load themes and media from the Qt Resource System. There are also some more variables in the theme file- {{ subject }} is replaced with the subject of the email, and {{ from }} is replaced with the name of the person who sent it.

The way the date is represented shows another feature of Grantlee. {{ date }} in the theme is a QDateTime object. The object can be passed through a filter which processes it before rendering. For example, the date and time filters allow the template writer to use QDateTime string formatting to render the date in different ways. The timesince filter shows how much time has passed between that date and now.

The rendering of the second screenshot is done with this theme. It is mostly similar to the first one, except that it also overrides the style block from base.html to define some more css. It also shows the use of a special {{ super }} variable. When used inside a block, {{ super }} contains the content of the block it overrides. In this case, the style from base.html is added to the rendered theme, and then some more css is defined inside that block.

In Grantlee terminology, the stuff inside {%  %} are called tags, and pipes("|") separate filters from the variables they operate on. There are many more tags and filters than just media_finder and date. See here for a list of all the tags and filters available by default. Note that downstreams can also define their own tags and filters using c++ or javascript/QtScript.

The code for this is in playground/pim/akonadi if you want to take it for a test run yourself. You can update the theme in real time using the akonadiconsole tool. The usual warnings about putting the kids safely in another room apply here though. This example requires KDE trunk to run, but Grantlee itself requires only QtCore4.5.

Lastly, don’t worry if you think my theming skills suck. The reason I wrote Grantlee was so that other people would be able to do the theming instead of me. If you want to get some cool themes into KMail 4.4 (or 4.5- not certain yet) and KJots you can start sending mockups now 🙂