Skip to content
Newer
Older
100644 135 lines (84 sloc) 6.34 KB
4dc441a @groue Guides/introduction.md is the documentation root: update all links
authored Aug 25, 2012
1 [up](introduction.md), [next](../../../tree/master/Guides/sample_code)
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
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 Jul 27, 2012
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 …
authored Aug 21, 2012
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 Jul 27, 2012
21
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
22 Observe the template rendering
23 ------------------------------
24
86003ca @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
25 ### Whole template rendering
26
27 The following methods are called before, and after the whole template rendering:
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
28
f009128 @groue More GFM :-)
authored Mar 5, 2012
29 ```objc
30 - (void)templateWillRender:(GRMustacheTemplate *)template;
31 - (void)templateDidRender:(GRMustacheTemplate *)template;
32 ```
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
33
7afeec3 @groue Introduce section delegates in the GRMustacheTemplate documentation
authored Jul 27, 2012
34 Section delegates are not sent these messages. Only template delegates are.
35
86003ca @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
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 Mar 5, 2012
39
f009128 @groue More GFM :-)
authored Mar 5, 2012
40 ```objc
459f57b @groue v4.1.0
authored Jun 30, 2012
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 Mar 5, 2012
43 ```
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
44
459f57b @groue v4.1.0
authored Jun 30, 2012
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 Mar 5, 2012
46
459f57b @groue v4.1.0
authored Jun 30, 2012
47 You can read the following properties of the *invocation* parameter:
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
48
86003ca @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
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 Mar 8, 2012
51 - `NSString *description`: a string that helps you locate the corresponding Mustache tag.
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
52
a4e64b8 @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
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 Jun 30, 2012
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 wit…
authored Aug 4, 2012
65 GRMustacheInterpretationFilterArgument,
459f57b @groue v4.1.0
authored Jun 30, 2012
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 wit…
authored Aug 4, 2012
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 Mar 5, 2012
74
16f24a3 @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
75
86003ca @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
76 ### A practical use: debugging templates
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
77
7afeec3 @groue Introduce section delegates in the GRMustacheTemplate documentation
authored Jul 27, 2012
78 You may, for instance, give your templates a delegate that locate missing keys:
86003ca @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
79
80 ```objc
459f57b @groue v4.1.0
authored Jun 30, 2012
81 - (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation
86003ca @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
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 Mar 5, 2012
86 // Log the missing key
71638db @groue v1.12.1
authored Mar 8, 2012
87 NSLog(@"GRMustache missing key: `%@` for %@", invocation.key, invocation.description);
86003ca @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
88 }
89 }
90 ```
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
91
71638db @groue v1.12.1
authored Mar 8, 2012
92 You'll get something like:
93
94 ```
35162b7 @groue Hard wrap documentation to 80 columns
authored Jul 1, 2012
95 GRMustache missing key: `items` for <GRMustacheInvocation: {{#items}} at line 23
96 in template /path/to/template.mustache>
71638db @groue v1.12.1
authored Mar 8, 2012
97 ```
98
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
99 Alter the template rendering
100 ----------------------------
101
459f57b @groue v4.1.0
authored Jun 30, 2012
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 Mar 5, 2012
103
08be4e8 @groue More precise wording about other Mustache implementations
authored Mar 5, 2012
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 Mar 5, 2012
105
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
106
0bebc11 @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
107 ### A practical use: providing default values for missing keys
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
108
0132163 @groue experiment with GitHub Flavored Markdown
authored Mar 5, 2012
109 ```objc
459f57b @groue v4.1.0
authored Jun 30, 2012
110 - (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation
0132163 @groue experiment with GitHub Flavored Markdown
authored Mar 5, 2012
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 wit…
authored Aug 4, 2012
114 invocation.returnValue = @"DEFAULT";
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
115 }
0132163 @groue experiment with GitHub Flavored Markdown
authored Mar 5, 2012
116 }
117 ```
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
118
fda93a5 @groue Update helpers and delegate documentation so that they better fit wit…
authored Aug 4, 2012
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 …
authored Aug 21, 2012
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
4dc441a @groue Guides/introduction.md is the documentation root: update all links
authored Aug 25, 2012
134 [up](introduction.md), [next](../../../tree/master/Guides/sample_code)
Something went wrong with that request. Please try again.