File: for_app_dev.dox

package info (click to toggle)
grantlee5 5.1.0-2.1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 4,152 kB
  • sloc: cpp: 24,299; python: 413; sh: 108; ruby: 24; makefile: 20
file content (435 lines) | stat: -rw-r--r-- 13,893 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
namespace Grantlee
{

/**

  @page for_app_dev Grantlee for application developers

  Integrating %Grantlee into applications is very simple. This page describes

  @li How to render a Template with a Context
  @li How to load Templates
  @li How to extend the syntax of %Grantlee
  @li Patterns of use of %Grantlee
  @li Differences between Django and %Grantlee

  If you are not already familiar with Django template syntax and structure, start with @ref for_themers. If you are already familiar with Django, you might find @ref differences_django informative.

  @section rendering_templates Rendering Templates

  @subsection creating_templates Creating Templates

  Rendering templates is also very easy in application code. A single Template may be rendered multiple times with different Context objects.

  @code
    Grantlee::Engine *engine = new Grantlee::Engine( this );
    Grantlee::Template t = engine->newTemplate("My name is {{ name }}.", "my_template_name");
    QVariantHash mapping;
    mapping.insert("name", "Grainne");
    Grantlee::Context c(mapping);

    t->render(&c); // Returns "My name is Grainne."

    mapping.insert("name", "Henry");
    c = Grantlee::Context(mapping);

    t->render(&c); // Returns "My name is Henry."
  @endcode

  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.

  @code
    Grantlee::Template t = engine->loadByName("template.html");

    t->render(&c)
  @endcode

  @subsection variables Variables

  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 @gr_var{variable} syntax or inside @gr_tag{control&nbsp;tags}. In the above example, we mapped the string <tt>"name"</tt> to the string <tt>"Grainne"</tt> and then to the string <tt>"Henry"</tt>. We can create more than just string mappings though.

  @code
    mapping.insert("myint", 6); // Can insert ints
    mapping.insert("mydouble", 6.5); // Can insert doubles
    mapping.insert("mybool", false); // Can insert bools

    QVariantList mylist;
    mylist << "Ingrid" << 3;
    mapping.insert("mylist", mylist); // Can insert QVariantList

    QVariantHash myhash;
    myhash.insert("James", "Artist");
    myhash.insert("Kiera", "Dreamer");
    mapping.insert("myhash", myhash); // Can insert QVariantHash

    QObject *obj;
    QVariant objVar = QVariant::fromValue(obj);
    mapping.insert("myobject", objVar); // Can insert QObject*
  @endcode

  It is additionally possible to insert any type of object or any container (not just QVariantHash and QVariantList) into the Context.
  @see @ref generic_types_and_templates.

  @section extending_grantlee Extending Grantlee

  %Grantlee has 5 extension points.

  - Custom object variables
  - Generic types and containers
  - Filters
  - Tags
  - Loaders

  @subsection custom_objects Custom objects

  As already noted, <tt>QObject*</tt> 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 If you are already familiar with Django you will know that creating wrappers is not necessary in Django. That is because python objects are already fully introspectable.

  @code
    #include "myperson.h"

    class PersonWrapper : public QObject
    {
      Q_OBJECT
      Q_PROPERTY(QString name READ name)
    public:
      PersonWrapper(const QString &name, int age);

      QString name() const;

      int age() const;

      QString clear();

    };

    ...

    PersonWrapper *linda = new PersonWrapper("Linda", 21);

    QVariant lindaVar = QVariant::fromValue<QObject*>(linda);

    mapping.insert("person", lindaVar);

    ...

    The name is {{ person.name }} and age is {{ person.age }}.

    // Will be rendered as
    // The name is Linda and age is .
  @endcode

  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

  @verbatim
    Q_PROPERTY(int age READ age)
  @endverbatim

  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&lt;PersonWrapper*&gt;() would work, but it is recommended to use QObject* instead. See also @ref 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.

  @note If you are familiar with Django you may be aware of the 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 @ref extension. For some example uses of %Grantlee, see @ref examples.

  @subsection custom_object_properties Custom Object Properties

  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:

  @code
    class Home : public QObject
    {
        Q_OBJECT
        Q_PROPERTY(int houseNumber READ houseNumber)
        Q_PROPERTY(QString streetName READ streetName)
        Q_PROPERTY(QString city READ city)
    public:
        // ...
    };
    Q_DECLARE_METATYPE(Home*)
  @endcode

  And we may wish to use it in our PersonWrapper object:

  @code
    class PersonWrapper : public QObject
    {
      Q_OBJECT
      Q_PROPERTY(QString name READ name)
      Q_PROPERTY(Home* home READ home)
    public:
      PersonWrapper(const QString &name, int age, Home *home);

      Home* home() const;

      // ...
    }
  @endcode

  And then use it in a template:

  @code
    <h1>{{ person.name }}</h1>
    House number: {{ person.home.houseNumber }}
    Street: {{ person.home.streetName }}
  @endcode

  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*:

  @code
    class PersonWrapper : public QObject
    {
      Q_OBJECT
      Q_PROPERTY(QString name READ name)
      Q_PROPERTY(QObject* home READ scriptableHome)
    public:
      PersonWrapper(const QString &name, int age, Home *home);

      QObject* scriptableHome() const { return home(); }
      Home* home() const;

      // ...
    }
  @endcode

  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.

  @code
    // Somewhere among other initializers
    Grantlee::registerMetaType<Home*>();

    // ...
    // Creating the context.

    PersonWrapper *person = new PersonWrapper;

    context.insert("person", person);

    t->render(&c);

    // ...
    // Template can now use home property as normal. Eg
     Street: {{ person.home.streetName }}
  @endcode

  Note that prior to %Grantlee version 0.1.9, Grantlee::registerMetaType&lt;Home*, QObject*&gt;(); must be used instead.

  Using containers such as QList with Q_PROPERTY macro is also possible.

  @code
    class PersonWrapper : public QObject
    {
      Q_OBJECT
      Q_PROPERTY(QString name READ name)
      Q_PROPERTY(QVariant friends READ friends)
    public:
      PersonWrapper(const QString &name, int age, Home *home);

      QVariant friends() const { return QVariant::fromValue(m_friends); }
      void setFriends(const QList<QObject*> friends) { m_friends = friends; }

      // ...

    private:
      QList<QObject*> m_friends;
    };
    Q_DECLARE_METATYPE(QList<QObject*>)
  @endcode

  It is also necessary to register QList<QObject*> with the Qt metatype system and with Grantlee

  @code
    Grantlee::registerSequentialContainer<QList<QObject*> >();
  @endcode

  @subsection 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 @ref generic_types_and_templates

  @subsection enumerator_variables Enumerators

  %Grantlee has built-in support for enumerators which use the Q_ENUMS macro.

  @code
  class MyClass : public QObject
  {
    Q_OBJECT
    Q_ENUMS(PersonName)
    Q_PROPERTY(PersonName personName READ personName)
  public:

    enum PersonName
    {
      Mike,
      Natalie,
      Oliver,
      Patrica = 9
      Quentin
    };

    MyClass(QObject *parent = 0 );

    PersonName personName() const { return Quentin; }

  };

  ...

  {
    QObject *object = new MyClass(this);
    context.insert("myObj", object);
    t->render(context);
  }
  @endcode

  The enums can be used and accessed in various ways. See QMetaEnum for details.

  @code
    Oliver is value {{ myObj.Oliver }}.
    // Output: "Oliver is value 2".

    ...

    Oliver key is {{ myObj.Oliver.key }}.
    // Output: "Oliver key is Oliver".

    ...

    Oliver value is {{ myObj.Oliver.value }}.
    // Output: "Oliver value is 2".

    ...

    Oliver scope is {{ myObj.Oliver.scope }}.
    // Output: "Oliver scope is MyClass".

    ...

    Oliver scope is {{ myObj.Oliver.name }}.
    // Output: "Oliver scope is PersonName".

    ...

    Patrica is value {{ myObj.Patrica }}.
    // Output: "Patrica is value 9".

    ...

    PersonName has {{ myObj.PersonName.keyCount }} items.
    // Output: "PersonName has 5 items".

    ...

    Second item is {{ myObj.PersonName.1 }}.
    // Output: "Second item is 1".

    ...

    Second item is {{ myObj.PersonName.1.key }}.
    // Output: "Second item is Natalie".

    ...

    Fourth item is {{ myObj.PersonName.3 }}.
    // Output: "Fourth item is 9".

    ...

    Fourth item is {{ myObj.PersonName.3.key }}.
    // Output: "Fourth item is Patrica".

    ...

    The personName property is {{ myObj.personName }}.
    // Output: "The personName property is 10".

    ...

    The personName property is {{ myObj.personName.key }}.
    // Output: "The personName property is Quentin".

    ...

    The personName type is {{ myObj.personName.scope }}.
    // Output: "The personName type is PersonName".

    ...

    The personName is {% with myObj.personName as var %}{{ var }}, {{ var.key }}{% endwith %}.
    // Output: "The personName is 10, Quentin".

    ...

    The enum is {% with myObj.PersonName as enum %}{{ enum.3 }}, {{ enum.4 }}, {{ enum.4.key }}{% endwith %}.
    // Output: "The enum is 9, 10, Quentin".

    ...

    The enum is {% for enum in myObj.PersonName %}{{ enum }} : {{ enum.key }}, {% endfor %}.
    // Output: "The enum 0 : Mike, 1 : Natalie, 2 : Oliver, 9 : Patrica, 10 : Quentin, ".

    ...

    The enum is {% for enum in myObj.PersonName %}
                    {% ifequal enum Oliver %}**{{ enum }} : {{ enum.key }}**
                    {% else %}{{ enum }} : {{ enum.key }},
                    {% endifequal %}
                {% endfor %}.
    // Output: "The enum 0 : Mike, 1 : Natalie, **2 : Oliver**, 9 : Patrica, 10 : Quentin, ".

    ...

    The enum is {% for enum in myObj.PersonName %}
                    {% ifequal enum myObj.personName %}**{{ enum }} : {{ enum.key }}**
                    {% else %}{{ enum }} : {{ enum.key }},
                    {% endifequal %}
                {% endfor %}.
    // Output: "The enum 0 : Mike, 1 : Natalie, 2 : Oliver, 9 : Patrica, **10 : Quentin**, ".
  @endcode

  Enumerators in the Qt namespaces are also supported.

  @code
    AlignRight value is {{ Qt.AlignRight }}.
    // Output: "AlignRight value is 2".

    ...

    AlignRight key is {{ Qt.AlignRight.key }}.
    // Output: "AlignRight value is AlignRight".

    ...

    AlignRight scope is {{ Qt.AlignRight.scope }}.
    // Output: "AlignRight scope is Qt".

    ...

    AlignRight name is {{ Qt.AlignRight.name }}.
    // Output: "AlignRight scope is Alignment".

    ...

    {% ifequal myObj.alignment Qt.AlignRight %}RightAligned{% else %}Not RightAligned{% endifequal %}.
    // Output: "RightAligned". or "Not RightAligned", depending on the value of myObj.alignment.

    ...
  @endcode

*/

}