Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 135 lines (84 sloc) 6.508 kb
78d3b1b @groue Fix guide link
authored
1 [up](../../../../GRMustache), [next](../../../tree/master/Guides/sample_code)
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
7afeec3 @groue Introduce section delegates in the GRMustacheTemplate documentation
authored
9 Template delegate and section delegates
10 ---------------------------------------
11
12 While rendering a template, several objects may get messages from GRMustache:
13
14 - The template's delegate itself, which you set via the `delegate` property of the GRMustacheTemplate class.
15 - Objects attached to sections, as long as they conform to the GRMustacheTemplateDelegate protocol.
16
17 The template's delegate can observe the full template rendering. However, sections delegates can only observe the rendering of their inner content. As sections get nested, a template gets more and more delegates.
18
d67b4cc @groue Guides/helpers.md refactoring + Insert Guides/localization.md in the doc...
authored
19 You'll find template delegate usages below. Section delegates are used in the [localization](sample_code/localization.md) sample code.
20
7afeec3 @groue Introduce section delegates in the GRMustacheTemplate documentation
authored
21
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
22 Observe the template rendering
23 ------------------------------
24
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
25 ### Whole template rendering
26
27 The following methods are called before, and after the whole template rendering:
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
28
f009128 @groue More GFM :-)
authored
29 ```objc
30 - (void)templateWillRender:(GRMustacheTemplate *)template;
31 - (void)templateDidRender:(GRMustacheTemplate *)template;
32 ```
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
33
7afeec3 @groue Introduce section delegates in the GRMustacheTemplate documentation
authored
34 Section delegates are not sent these messages. Only template delegates are.
35
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
36 ### Tag rendering
37
38 The following methods are called before, and after the rendering of substitution and sections tags (`{{name}}` and `{{#name}}...{{/name}}`):
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
39
f009128 @groue More GFM :-)
authored
40 ```objc
459f57b @groue v4.1.0
authored
41 - (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation;
42 - (void)template:(GRMustacheTemplate *)template didInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation;
f009128 @groue More GFM :-)
authored
43 ```
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
44
459f57b @groue v4.1.0
authored
45 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
46
459f57b @groue v4.1.0
authored
47 You can read the following properties of the *invocation* parameter:
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
48
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
49 - `id returnValue`: the return value of the invocation.
50 - `NSString *key`: the key that did provide this value.
71638db @groue v1.12.1
authored
51 - `NSString *description`: a string that helps you locate the corresponding Mustache tag.
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
52
a4e64b8 @groue more GRMustacheTemplateDelegate documentation
authored
53 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.
54
459f57b @groue v4.1.0
authored
55 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`.
56
57 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.
58
59 The *interpretation* parameter tells you how the return value of the invocation is used:
60
61 ```objc
62 typedef enum {
63 GRMustacheInterpretationSection,
64 GRMustacheInterpretationVariable,
fda93a5 @groue Update helpers and delegate documentation so that they better fit with f...
authored
65 GRMustacheInterpretationFilterArgument,
459f57b @groue v4.1.0
authored
66 } GRMustacheInterpretation;
67 ```
68
69 `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.
70
71 `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.
72
fda93a5 @groue Update helpers and delegate documentation so that they better fit with f...
authored
73 `GRMustacheInterpretationFilterArgument` tells you that the return value is about to be processed by a filter such as `{{ f(name) }}`. See [Guides/filters.md](filters.md) for more information.
04bd01a @groue wording
authored
74
16f24a3 @groue more GRMustacheTemplateDelegate documentation
authored
75
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
76 ### A practical use: debugging templates
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
77
7afeec3 @groue Introduce section delegates in the GRMustacheTemplate documentation
authored
78 You may, for instance, give your templates a delegate that locate missing keys:
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
79
80 ```objc
459f57b @groue v4.1.0
authored
81 - (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
82 {
83 // When returnValue is nil, GRMustache could not find any value to render.
84 if (invocation.returnValue == nil) {
85
81323cd @groue more GRMustacheTemplateDelegate documentation
authored
86 // Log the missing key
71638db @groue v1.12.1
authored
87 NSLog(@"GRMustache missing key: `%@` for %@", invocation.key, invocation.description);
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
88 }
89 }
90 ```
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
91
71638db @groue v1.12.1
authored
92 You'll get something like:
93
94 ```
35162b7 @groue Hard wrap documentation to 80 columns
authored
95 GRMustache missing key: `items` for <GRMustacheInvocation: {{#items}} at line 23
96 in template /path/to/template.mustache>
71638db @groue v1.12.1
authored
97 ```
98
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
99 Alter the template rendering
100 ----------------------------
101
459f57b @groue v4.1.0
authored
102 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
103
08be4e8 @groue More precise wording about other Mustache implementations
authored
104 **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
105
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
106
0bebc11 @groue more GRMustacheTemplateDelegate documentation
authored
107 ### A practical use: providing default values for missing keys
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
108
0132163 @groue experiment with GitHub Flavored Markdown
authored
109 ```objc
459f57b @groue v4.1.0
authored
110 - (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation
0132163 @groue experiment with GitHub Flavored Markdown
authored
111 {
112 // When returnValue is nil, GRMustache could not find any value to render.
113 if (invocation.returnValue == nil) {
fda93a5 @groue Update helpers and delegate documentation so that they better fit with f...
authored
114 invocation.returnValue = @"DEFAULT";
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
115 }
0132163 @groue experiment with GitHub Flavored Markdown
authored
116 }
117 ```
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
118
fda93a5 @groue Update helpers and delegate documentation so that they better fit with f...
authored
119 ### Relationship with filters and helpers
120
121 Usually, [filters](filters.md) and [helpers](helpers.md) should do the trick when you want to alter a template's rendering.
122
123 However, they both require to be explicited invoked from the template: `{{#helper}}...{{/helper}}`, and `{{ filter(...) }}`.
124
125 GRMustacheTemplateDelegate will help you when you can not, or do not want, to embed your extra behaviors right into the template.
126
127
d67b4cc @groue Guides/helpers.md refactoring + Insert Guides/localization.md in the doc...
authored
128 Sample code
129 -----------
130
131 The [localization.md](sample_code/localization.md) sample code uses section delegates for localizing portions of template.
132
133
78d3b1b @groue Fix guide link
authored
134 [up](../../../../GRMustache), [next](../../../tree/master/Guides/sample_code)
Something went wrong with that request. Please try again.