Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 107 lines (69 sloc) 5.13 kb
18da0ef @groue Number formatting sample code
authored
1 [up](../../../../GRMustache), [next](sample_code.md)
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
2
3 GRMustacheTemplateDelegate protocol
4 ===================================
5
6 This protocol lets you observe, and possibly alter the rendering of a template.
7
8
9 Observe the template rendering
10 ------------------------------
11
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
12 ### Whole template rendering
13
14 The following methods are called before, and after the whole template rendering:
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
15
f009128 @groue More GFM :-)
authored
16 ```objc
17 - (void)templateWillRender:(GRMustacheTemplate *)template;
18 - (void)templateDidRender:(GRMustacheTemplate *)template;
19 ```
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
20
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
21 ### Tag rendering
22
23 The following methods are called before, and after the rendering of substitution and sections tags (`{{name}}` and `{{#name}}...{{/name}}`):
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
24
f009128 @groue More GFM :-)
authored
25 ```objc
459f57b @groue v4.1.0
authored
26 - (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation;
27 - (void)template:(GRMustacheTemplate *)template didInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation;
f009128 @groue More GFM :-)
authored
28 ```
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
29
459f57b @groue v4.1.0
authored
30 Maybe verbose. But quite on target: as a matter of fact, in order to render a tag, GRMustache has to *invoke* the tag name on the rendered object, the one you've given to the template, and then to *interpret* it.
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
31
459f57b @groue v4.1.0
authored
32 You can read the following properties of the *invocation* parameter:
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
33
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
34 - `id returnValue`: the return value of the invocation.
35 - `NSString *key`: the key that did provide this value.
71638db @groue v1.12.1
authored
36 - `NSString *description`: a string that helps you locate the corresponding Mustache tag.
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
37
a4e64b8 @groue more GRMustacheTemplateDelegate documentation
authored
38 Note that those methods do not allow you to build a complete "stack trace" of GRMustache rendering. They are not called for each accessed key. They are called for each tag rendering, which is quite different.
39
459f57b @groue v4.1.0
authored
40 For instance, a tag like `{{person.name}}` is rendered once. Thus `template:willInterpretReturnValueOfInvocation:as:` will be called once. If the person has been found, the invocation's key will be `@"name"`, and the return value the name of the person. If the person could not be found, the key will be `@"person"`, and the return value `nil`.
41
42 Also: if a section tag `{{#name}}...{{/name}}` is provided with an NSArray, its content is rendered several times. However `template:willInterpretReturnValueOfInvocation:as:` will be called once, with the array stored in the return value of the invocation.
43
44 The *interpretation* parameter tells you how the return value of the invocation is used:
45
46 ```objc
47 typedef enum {
48 GRMustacheInterpretationSection,
49 GRMustacheInterpretationVariable,
50 } GRMustacheInterpretation;
51 ```
52
53 `GRMustacheInterpretationVariable` tells you that the return value is rendered by a Mustache variable tag such as `{{name}}`. Basically, GRMustache simply invokes its `description` method. See [Guides/runtime.md](runtime.md) for more information.
54
55 `GRMustacheInterpretationSection` tells you that the return value is used by a Mustache section such as `{{#name}}...{{/name}}`. Mustache sections are versatile: there are boolean sections, loop sections, and lambda sections, and this depends solely on the rendered value, that is to say: the return value of the invocation. Again, see [Guides/runtime.md](runtime.md) for more information.
56
57 You will find an actual use of this *interpretation* parameter in the [number formatting sample code](sample_code/number_formatting.md).
04bd01a @groue wording
authored
58
16f24a3 @groue more GRMustacheTemplateDelegate documentation
authored
59
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
60 ### A practical use: debugging templates
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
61
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
62 You may, for instance, locate keys that could not find any data:
63
64 ```objc
459f57b @groue v4.1.0
authored
65 - (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
66 {
67 // When returnValue is nil, GRMustache could not find any value to render.
68 if (invocation.returnValue == nil) {
69
81323cd @groue more GRMustacheTemplateDelegate documentation
authored
70 // Log the missing key
71638db @groue v1.12.1
authored
71 NSLog(@"GRMustache missing key: `%@` for %@", invocation.key, invocation.description);
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
72 }
73 }
74 ```
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
75
71638db @groue v1.12.1
authored
76 You'll get something like:
77
78 ```
52441fb @groue wording
authored
79 GRMustache missing key: `items` for <GRMustacheInvocation: {{#items}} at line 23 in template /path/to/template.mustache>
71638db @groue v1.12.1
authored
80 ```
81
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
82 Alter the template rendering
83 ----------------------------
84
459f57b @groue v4.1.0
authored
85 The `returnValue` property of the *invocation* parameter can be written. If you set it in `template:willInterpretReturnValueOfInvocation:as:`, GRMustache will render the value you have provided.
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
86
08be4e8 @groue More precise wording about other Mustache implementations
authored
87 **Warning: If your goal is to design templates that remain compatible with [other Mustache implementations](https://github.com/defunkt/mustache/wiki/Other-Mustache-implementations), use this feature with great care.**
62ed17f @groue more GRMustacheTemplateDelegate documentation
authored
88
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
89
0bebc11 @groue more GRMustacheTemplateDelegate documentation
authored
90 ### A practical use: providing default values for missing keys
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
91
0132163 @groue experiment with GitHub Flavored Markdown
authored
92 ```objc
459f57b @groue v4.1.0
authored
93 - (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation
0132163 @groue experiment with GitHub Flavored Markdown
authored
94 {
95 // When returnValue is nil, GRMustache could not find any value to render.
96 if (invocation.returnValue == nil) {
0bebc11 @groue more GRMustacheTemplateDelegate documentation
authored
97 invocation.returnValue = @"[DEFAULT]";
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
98 }
0132163 @groue experiment with GitHub Flavored Markdown
authored
99 }
100 ```
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
101
47684b7 @groue more GRMustacheTemplateDelegate documentation
authored
102 ### Even more practical uses: sample code
103
104 In the next guide, [sample_code.md](sample_code.md), you'll see the GRMustacheTemplateDelegate protocol in action.
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
105
18da0ef @groue Number formatting sample code
authored
106 [up](../../../../GRMustache), [next](sample_code.md)
Something went wrong with that request. Please try again.