Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 131 lines (81 sloc) 5.873 kb
4dc441a @groue Guides/introduction.md is the documentation root: update all links
authored
1 [up](introduction.md), [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.
ed26c85 @groue v5.3.0
authored
15 - Objects attached to section tags, as long as they conform to the GRMustacheTemplateDelegate protocol.
7afeec3 @groue Introduce section delegates in the GRMustacheTemplate documentation
authored
16
ed26c85 @groue v5.3.0
authored
17 The template's delegate can observe the full template rendering. However, Delegates of section tags can only observe the rendering of their inner content. As sections get nested, a template gets more and more delegates.
7afeec3 @groue Introduce section delegates in the GRMustacheTemplate documentation
authored
18
ed26c85 @groue v5.3.0
authored
19 You'll find template delegate usages below. Delegates of section tags are used in the [localization](sample_code/localization.md) sample code.
d67b4cc @groue Guides/helpers.md refactoring + Insert Guides/localization.md in the …
authored
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
ed26c85 @groue v5.3.0
authored
34 Delegates of section tags are not sent these messages. Only template delegates are.
7afeec3 @groue Introduce section delegates in the GRMustacheTemplate documentation
authored
35
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
36 ### Tag rendering
37
ed26c85 @groue v5.3.0
authored
38 The following methods are called before, and after the rendering of variable 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
7924382 @groue v5.0.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 expression 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.
71638db @groue v1.12.1
authored
50 - `NSString *description`: a string that helps you locate the corresponding Mustache tag.
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
51
e12baf0 @groue Fix delegate.md guide so that is does not document the removed GRMust…
authored
52 Note that those methods do not allow you to build a complete "stack trace" of a template rendering.
a4e64b8 @groue more GRMustacheTemplateDelegate documentation
authored
53
7924382 @groue v5.0.0
authored
54 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 return value will be the name of the person. If the person could not be found, the return value will be `nil`.
459f57b @groue v4.1.0
authored
55
56 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.
57
58 The *interpretation* parameter tells you how the return value of the invocation is used:
59
60 ```objc
61 typedef enum {
ed26c85 @groue v5.3.0
authored
62 GRMustacheSectionTagInterpretation,
63 GRMustacheVariableTagInterpretation,
459f57b @groue v4.1.0
authored
64 } GRMustacheInterpretation;
65 ```
66
4f79605 @groue Document the rendering of lists by variable tags.
authored
67 `GRMustacheVariableTagInterpretation` tells you that the return value is rendered by a Mustache variable tag such as `{{name}}`. `GRMustacheSectionTagInterpretation` tells you that the return value is used by a Mustache section tag such as `{{#name}}...{{/name}}`.
459f57b @groue v4.1.0
authored
68
4f79605 @groue Document the rendering of lists by variable tags.
authored
69 Given a value, both kinds of tags do not behave the same. For example, a variable tag will render "0" when given a false boolean, when a section will simply not render at all.
70
71 See [Guides/runtime.md](runtime.md) for more information.
459f57b @groue v4.1.0
authored
72
16f24a3 @groue more GRMustacheTemplateDelegate documentation
authored
73
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
74 ### A practical use: debugging templates
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
75
e12baf0 @groue Fix delegate.md guide so that is does not document the removed GRMust…
authored
76 You may, for instance, give your templates a delegate that locate missing values:
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
77
78 ```objc
459f57b @groue v4.1.0
authored
79 - (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
80 {
81 // When returnValue is nil, GRMustache could not find any value to render.
82 if (invocation.returnValue == nil) {
e12baf0 @groue Fix delegate.md guide so that is does not document the removed GRMust…
authored
83 NSLog(@"GRMustache missing value for %@", invocation.description);
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
84 }
85 }
86 ```
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
87
71638db @groue v1.12.1
authored
88 You'll get something like:
89
90 ```
e12baf0 @groue Fix delegate.md guide so that is does not document the removed GRMust…
authored
91 GRMustache missing value for <GRMustacheInvocation: {{#items}} at line 23
35162b7 @groue Hard wrap documentation to 80 columns
authored
92 in template /path/to/template.mustache>
71638db @groue v1.12.1
authored
93 ```
94
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
95 Alter the template rendering
96 ----------------------------
97
459f57b @groue v4.1.0
authored
98 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
99
08be4e8 @groue More precise wording about other Mustache implementations
authored
100 **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
101
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
102
0bebc11 @groue more GRMustacheTemplateDelegate documentation
authored
103 ### A practical use: providing default values for missing keys
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
104
0132163 @groue experiment with GitHub Flavored Markdown
authored
105 ```objc
459f57b @groue v4.1.0
authored
106 - (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation
0132163 @groue experiment with GitHub Flavored Markdown
authored
107 {
108 // When returnValue is nil, GRMustache could not find any value to render.
109 if (invocation.returnValue == nil) {
fda93a5 @groue Update helpers and delegate documentation so that they better fit wit…
authored
110 invocation.returnValue = @"DEFAULT";
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
111 }
0132163 @groue experiment with GitHub Flavored Markdown
authored
112 }
113 ```
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
114
fda93a5 @groue Update helpers and delegate documentation so that they better fit wit…
authored
115 ### Relationship with filters and helpers
116
117 Usually, [filters](filters.md) and [helpers](helpers.md) should do the trick when you want to alter a template's rendering.
118
7924382 @groue v5.0.0
authored
119 However, they both require to be explicitly invoked from the template: `{{#helper}}...{{/helper}}`, and `{{ filter(...) }}`.
fda93a5 @groue Update helpers and delegate documentation so that they better fit wit…
authored
120
121 GRMustacheTemplateDelegate will help you when you can not, or do not want, to embed your extra behaviors right into the template.
122
123
d67b4cc @groue Guides/helpers.md refactoring + Insert Guides/localization.md in the …
authored
124 Sample code
125 -----------
126
ed26c85 @groue v5.3.0
authored
127 The [localization.md](sample_code/localization.md) sample code uses delegates of section tags for localizing portions of a template.
d67b4cc @groue Guides/helpers.md refactoring + Insert Guides/localization.md in the …
authored
128
129
4dc441a @groue Guides/introduction.md is the documentation root: update all links
authored
130 [up](introduction.md), [next](../../../tree/master/Guides/sample_code)
Something went wrong with that request. Please try again.