Grantlee
5.1.0
|
Integrating Grantlee into applications is very simple. This page describes
If you are not already familiar with Django template syntax and structure, start with Grantlee for theme artists.. If you are already familiar with Django, you might find Differences between Django and Grantlee informative.
Rendering templates is also very easy in application code. A single Template may be rendered multiple times with different Context objects.
Ususally, applications will not create a Template directly, but instead use a Grantlee::Engine to load external files. This allows artists to define the template without needing to recompile.
A Context object maps a string to another object for reference in the template. String keys in the Context object are available as variables in the Template, and can be used with the {{ variable }}
syntax or inside {% control tags %}
. In the above example, we mapped the string "name"
to the string "Grainne"
and then to the string "Henry"
. We can create more than just string mappings though.
It is additionally possible to insert any type of object or any container (not just QVariantHash and QVariantList) into the Context.
Grantlee has 5 extension points.
As already noted, QObject*
can be inserted into templates. The recommended way to insert custom objects into templates is to create QObject wrappers for your objects. As QObject is introspectable, this will allow lookups to work in a way you define.
Note that the 'name' of person is accessible in the template, but the 'age' is not. Note also that rendering fails silently if the method can not be found. Only methods which have a corresponding Q_PROPERTY declaration are accessible from templates. To make age accessible in the template, we would need to add
Q_PROPERTY(int age READ age)
to the class. Note also that those methods are const. Rendering a template should never change an object it is rendering. Always make sure the READ properties of your wrapper objects are const. It is also possible to lookup dynamic properties of QObjects. In the case of dynamic properties, the property name must be UTF-8 encoded.
Finally, note that the person object (Linda) is inserted into the QVariant as a QObject*, not as a PersonWrapper*. Otherwise, the compiler would generate an error message about an unregistered datatype PersonWrapper*. While using Q_DECLARE_METATYPE(PersonWrapper*) would make the compiler error go away, it would still not be possible to use the Linda object in Grantlee templates. Using Grantlee::registerMetaType<PersonWrapper*>() would work, but it is recommended to use QObject* instead. See also Custom Object Properties.
If you already have QObjects in your application which would be suitable for use in templates, you only need to add some Q_PROPERTY entries to the classes to make them accessible to Grantlee.
For most uses of Grantlee, this is enough to get make an application themable easily and quickly. For more advanced usage, see Extending the template system. For some example uses of Grantlee, see Examples of Grantlee use.
In Qt4 there are some limitations regarding the types that may be used in Q_PROPERTY entries which should be read by Grantlee.
We might define a Home object like this:
And we may wish to use it in our PersonWrapper object:
And then use it in a template:
This will not work with Qt4. The home property will not be readable and there will be a message about an unregistered datatype 'Home*'.
The workaround is to specify the type of the home property to be a QObject* instead of a Home*:
In this example, we leave the home() method intact because we may want to use the Home* type from C++, but we add a scriptableHome() method which returns a QObject* instead of a Home*. This method is then used in the READ component of the Q_PROPERTY.
The above is the recommended method of using Q_PROPERTY with QObject derived types, however, if the class containing the Q_PROPERTY (PersonWrapper in the example above) can not be modified, it is still possible to make the property accessible to Grantlee by using the Grantlee::registerMetaType() method near the start of the program.
Note that prior to Grantlee version 0.1.9, Grantlee::registerMetaType<Home*, QObject*>(); must be used instead.
Using containers such as QList with Q_PROPERTY macro is also possible.
It is also necessary to register QList<QObject*> with the Qt metatype system and with Grantlee
An alternative to writing wrapper QObject classes with Q_PROPERTY macros is to use the Grantlee::MetaType system to provide introspection for any type or any container. This subject is treated in detail in Generic type and template support
Grantlee has built-in support for enumerators which use the Q_ENUMS macro.
The enums can be used and accessed in various ways. See QMetaEnum for details.
Enumerators in the Qt namespaces are also supported.