Archive for June, 2009

Some clarifications regarding Grantlee

June 27, 2009

It seems that my initial email announcing the existence of Grantlee had too much of the wrong kind of information and not enough context. I’ve been speaking to a few people about it since at Linux Tag and elsewhere. I’ll try to address the problems here.

String Templates are not C++ templates

Some people saw ‘template system’, and assumed that Grantlee was about C++ templates. Not so. The templates I’m talking about are more like the kind of templates used for string substitution. For example, ‘Hello %NAME’ might be a template which could have ‘%NAME’ substituted for anything else. Grantlee brings a lot more features and flexibility than just plain string substitution though.

Grantlee allows ‘tags’ such as if conditions, for loops, cycles, and even custom tags using the QtPlugin and QtScript systems. An example template for a blog homepage might look like this:

    <h1>My Blog, by {{ }}</h1>
    <h2>Recent entries</h2>
    <div class="bloglist">
      {% for entry in blog_entries %}
      <h2>{{ entry.title }}</h2>
      <h3>{{ }}</h3>
      <div class="blogentry">
       {{ entry.content }}
    {% endfor %}

It is of course not limited to blog homepages. The entry in the above example is just a QObject with some properties title, date and content. Any application can create QObjects like this and send them to the Template to be rendered. The primary benefit of this is that Templates can come from external data files and can be changed or updated without recompiling the application. The syntax of these templates is the same as the Templates in the Django framework.

So What is Django?

Django is a web framework written in the python language. It is growing in popularity particularly with news sites. The design of Django is split into three main parts: Models, Views and Templates.

The Models system in Django represents the database of a website. It’s an abstraction layer over tables, relations, joins etc, which allows website creators to ignore the details of specific databases (eg, MySQL, postgres etc), and just deal with objects from their database. The objects might be users, blog entries etc.

The Views system in Django is the logical part. When your browser requests a page- a blog entry, or a list of recent entries for example, the Views system first queries the models system to get the data to send back to the browser. For example, a particular view might first get the 10 most recent blog entries and then render a result to send back to the browser.

The rendering of the result is performed by the Django Template system. The Template system loads some plain text files which describe the html to send back to the browser. Because the templates come from external files, and are not ‘tied to’ the view, there is a clear separation of concerns. The Views system retrieves the correct data from the database, and the Template system generates the returned html.

The view and the template do not interact with each other directly in a meaningful way. The view creates some objects (In the above case it creates a list of blog objects called ‘blog_entries’, and a blog_owner object for the title), and passes them to the Template system to render the response to the browser. This separation has several benefits. Firstly, it allows changing the appearance of the web site without changing any of the code to handle the database or the HTTP requests. Secondly, it allows the person writing the Models and the Views (concerned with logic) to be a different person to the person creating the Templates (concerned with appearance of the web page). People with good coding skills may not have good artistic abilities.

So Grantlee is a web framework written in Qt?

Nope. Grantlee is the Template part of Django described above ported over to C++/Qt. If someone was writing a web framework in Qt using a similar design to Django, Grantlee could be used to provide the templating features of such a project, but that is not the primary aim. The benefit Grantlee provides to KDE (and Qt) applications, then, is to provide easy theming capabilities to application writers. In the same way that Django Views only retrieve or create objects and then pass them to Templates for rendering, so Qt applications need only to create QObjects and pass them to Grantlee for rendering.

Templates come from external data files, which means that the appearance of the data being presented can be changed without recompiling the application or writing any additional code. Therefore, the appearance of rendered data can be decided not by the application writer, but by an entirely different person with an eye for aesthetics. There was a proposal some time ago to allow user customising of css to modify how KMail reader looks. Grantlee allows the themer to modify not only the css, but also the html code which controls how such things look.

Ok, It’s a theming system. Can I see it?

So far there are a small handful of demo applications ported to Grantlee and some screenshots here. See the template files for the books example, the dbus-chat example, and the example mail application.

What’s next? Can I use it?

Not yet. There are a few incomplete bits blocking an initial release. Next steps will probably be porting KMail and KJots to Grantlee in time for KDE 4.4. Other issues such as packaging structure and scope need to be solved too. I’ve already spoken about that to Frank Karlitschek of about package structure and GetHotNewStuff integration to allow users to share themes with each other.

How do I find out more?

Come to my talk of course.

Comparison of KDE documentation with other FLOSS projects

June 25, 2009

While reading some Django blogs, I came across a post from Mohammad Almarzouq comparing the ratio of Django documentation to lines of code against other Free Software projects.

The background of his png is transparent and unreadable against the checkered background in gwenview. I put a version with a white background here.

There are a few KDE projects there including Amarok, Digikam, kdelibs etc, many near the top of the ‘bulk’. Could be interesting if you happen to like that kind of thing. He doesn’t say what exactly he’s counting though. It’s probably a comparison of the number of lines in module/doc/ against module/. Anyone want to try it and see what you get?

Testing non-trivial generic proxy models.

June 23, 2009

Now that Grantlee is out the door I’ve turned my attention back to Akonadi for the moment. My role in Akonadi is that of Models writer and noise maker, primarily the former at the moment.

In Akonadi, we have a relatively simple to use model called EntityTreeModel which represents a tree of collections PIM items. That might mean emails, or contacts etc. Applications have needs like ‘show me all contacts in all child collections below this collection’. The functionality is similar to the current behaviour of Akregator for example. To satisfy that we have a generic proxy model DescendentEntitiesProxyModel, which is based on the older FlatCollectionProxyModel in Akonadi.

There is also the use-case of ‘Show me content of this collection in that view’. This behaviour is similar to the behaviour of many other PIM applications. Select a folder in the collection tree in KMail and you see the emails in that collection in the email list on the right. The current KMail implementation works only with one selected collection at a time however. For a more generic solution to the problem, we now also have SelectionProxyModel, which uses a QItemSelectionModel which manages filtering of its source model. Whatever is selected in one view will be shown on its own in another view- even for non-contiguous or block selections. This takes away any need to mess around with mapToSource, mapFromSource, and setRootIndex.

Already I can think of two other proxy models that I will probably be writing over the next few months for Akonadi, so I needed a good test suite for them. While writing the above models, I was writing small test cases for various issues to reproduce various Qt bugs. Eventually, I wrote an easily manipulatable model- DynamicTreeModel which uses the Command Pattern to create any kind of tree I wanted to test. Using that I can insert rows and subtrees, remove rows, move rows, and change row data by creating lists of Command objects and executing them.

For a while I was using DynamicTreeModel together with ModelTest as my proxymodel unit test suite. The limitations of this is that ModelTest only checks a model under test for consistency, not for correctness. For example, if a proxy model receives a dataChanged signal from its sourceModel, but doesn’t react to it or emit any signals to the outside world about it, ModelTest still passes. That’s fine in some cases, but really you need some way to specify whether a signal should be emitted or not, and that the correct signal is emitted. Lastly, you need to assure that any QPersistentModelIndexes from the model are updated to their correct values after reacting to the signal.

Instead of writing tests to handle all that once for each proxy model, I decided to write it only once. Now I have a ProxyModelTest class, which is half a unit test case. It manipulates a DynamicTreeModel into emitting a wide range of signals, each of which the proxy model will have to have some reaction to (even if it’s ‘Do nothing’). The other half of each unit test specifies what signals the proxy should emit for each signal that it recieves from ProxyModelTest which QPersistentModelIndexes should be updated, and what they should be updated to.

I’ve already written some tests for DescendantEntitesProxyModel and SelectionProxyModel using it.

My solution so far is quite incomplete, but only just started.

How do you test proxy models? Any other ideas?

Grantlee now available

June 18, 2009

Today I published the source code of the Grantlee template system, which I’m due to speak about at GCDS.

Briefly, Grantlee is a string template system- A port of the Django template system to Qt. See here for a primer on what the system can do.

The apidox are for the moment here and there’s some more details here.

Apologies if this hit your inbox multiple times. I announced it in a few places.

Slides from April

June 15, 2009

I still had the slides lying around from my talk at the Linux Collaboration Summit back in April, so I thought I’d post them here.

The style and content is modified from Jos’ generic KDE4 presentation. The Pillars of KDE images were made by Kamaleshwar Morjal for a few years ago. Get them on Flickr in high res if you want to use them.