Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 129 lines (80 sloc) 6.02 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 doc...
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 GRMustach...
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
ed26c85 @groue v5.3.0
authored
67 `GRMustacheVariableTagInterpretation` 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.
459f57b @groue v4.1.0
authored
68
ed26c85 @groue v5.3.0
authored
69 `GRMustacheSectionTagInterpretation` tells you that the return value is used by a Mustache section tag 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.
459f57b @groue v4.1.0
authored
70
16f24a3 @groue more GRMustacheTemplateDelegate documentation
authored
71
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
72 ### A practical use: debugging templates
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
73
e12baf0 @groue Fix delegate.md guide so that is does not document the removed GRMustach...
authored
74 You may, for instance, give your templates a delegate that locate missing values:
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
75
76 ```objc
459f57b @groue v4.1.0
authored
77 - (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
78 {
79 // When returnValue is nil, GRMustache could not find any value to render.
80 if (invocation.returnValue == nil) {
e12baf0 @groue Fix delegate.md guide so that is does not document the removed GRMustach...
authored
81 NSLog(@"GRMustache missing value for %@", invocation.description);
86003ca @groue more GRMustacheTemplateDelegate documentation
authored
82 }
83 }
84 ```
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
85
71638db @groue v1.12.1
authored
86 You'll get something like:
87
88 ```
e12baf0 @groue Fix delegate.md guide so that is does not document the removed GRMustach...
authored
89 GRMustache missing value for <GRMustacheInvocation: {{#items}} at line 23
35162b7 @groue Hard wrap documentation to 80 columns
authored
90 in template /path/to/template.mustache>
71638db @groue v1.12.1
authored
91 ```
92
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
93 Alter the template rendering
94 ----------------------------
95
459f57b @groue v4.1.0
authored
96 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
97
08be4e8 @groue More precise wording about other Mustache implementations
authored
98 **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
99
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
100
0bebc11 @groue more GRMustacheTemplateDelegate documentation
authored
101 ### A practical use: providing default values for missing keys
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
102
0132163 @groue experiment with GitHub Flavored Markdown
authored
103 ```objc
459f57b @groue v4.1.0
authored
104 - (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation
0132163 @groue experiment with GitHub Flavored Markdown
authored
105 {
106 // When returnValue is nil, GRMustache could not find any value to render.
107 if (invocation.returnValue == nil) {
fda93a5 @groue Update helpers and delegate documentation so that they better fit with f...
authored
108 invocation.returnValue = @"DEFAULT";
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
109 }
0132163 @groue experiment with GitHub Flavored Markdown
authored
110 }
111 ```
79d2814 @groue GRMustacheTemplateDelegate documentation
authored
112
fda93a5 @groue Update helpers and delegate documentation so that they better fit with f...
authored
113 ### Relationship with filters and helpers
114
115 Usually, [filters](filters.md) and [helpers](helpers.md) should do the trick when you want to alter a template's rendering.
116
7924382 @groue v5.0.0
authored
117 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 with f...
authored
118
119 GRMustacheTemplateDelegate will help you when you can not, or do not want, to embed your extra behaviors right into the template.
120
121
d67b4cc @groue Guides/helpers.md refactoring + Insert Guides/localization.md in the doc...
authored
122 Sample code
123 -----------
124
ed26c85 @groue v5.3.0
authored
125 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 doc...
authored
126
127
4dc441a @groue Guides/introduction.md is the documentation root: update all links
authored
128 [up](introduction.md), [next](../../../tree/master/Guides/sample_code)
Something went wrong with that request. Please try again.