Grantlee 5.3.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 very easy in application code. A single Template may be rendered multiple times with different Context objects.
Usually, applications do 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.
Instances of 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 PersonWrapper
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 QObject
s. In the case of dynamic properties, the property name must be UTF-8 encoded.
If you already have QObject
s 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.
alters_data
attribute for methods. This method of using wrappers and const
is the equivalent to the alters_data
attribute. You the wrapper writer choose the properties which will be accessible from the templates and makes them const
, so there's no need to mark other methods as alters_data
.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.
The broad introspection features of Qt5 are relied upon by Grantlee via the Q_PROPERTY
macro. Most types used with that macro may be accessed in Grantlee templates without further code.
We can define a Home
type like this:
And we can use it in a Q_PROPERTY
macro in our PersonWrapper
type:
And then use it in a template:
Using containers such as QList and QSharedPointer with the Q_PROPERTY
macro is also possible.
Classes which do not derive from QObject, but which are decorated with the Q_GADGET
and <Q_PROPERTY/tt> macros may also be used as expected.
generic_variables
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
Enumerators
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.