Skip to content
Newer
Older
100644 91 lines (59 sloc) 3.79 KB
18da0ef @groue Number formatting sample code
authored Mar 5, 2012
1 [up](../../../../GRMustache), [next](sample_code.md)
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
9 Observe the template rendering
10 ------------------------------
11
86003ca @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
12 ### Whole template rendering
13
14 The following methods are called before, and after the whole template rendering:
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
15
f009128 @groue More GFM :-)
authored Mar 5, 2012
16 ```objc
17 - (void)templateWillRender:(GRMustacheTemplate *)template;
18 - (void)templateDidRender:(GRMustacheTemplate *)template;
19 ```
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
20
86003ca @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
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 Mar 5, 2012
24
f009128 @groue More GFM :-)
authored Mar 5, 2012
25 ```objc
26 - (void)template:(GRMustacheTemplate *)template willRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation;
27 - (void)template:(GRMustacheTemplate *)template didRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation;
28 ```
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
29
86003ca @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
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.
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
31
32 You can read the following properties of the *invocation* argument:
33
86003ca @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
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 Mar 8, 2012
36 - `NSString *description`: a string that helps you locate the corresponding Mustache tag.
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
37
a4e64b8 @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
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
40 For instance, a tag like `{{person.name}}` is rendered once. Thus `template:willRenderReturnValueOfInvocation:` 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`.
04bd01a @groue wording
authored Mar 5, 2012
41
16f24a3 @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
42 Also: if a section tag `{{#name}}...{{/name}}` is provided with an NSArray, it will be rendered several times. However `template:willRenderReturnValueOfInvocation:` will be called once, with the array stored in the return value of the invocation.
43
86003ca @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
44 ### A practical use: debugging templates
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
45
86003ca @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
46 You may, for instance, locate keys that could not find any data:
47
48 ```objc
49 - (void)template:(GRMustacheTemplate *)template willRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation
50 {
51 // When returnValue is nil, GRMustache could not find any value to render.
52 if (invocation.returnValue == nil) {
53
81323cd @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
54 // Log the missing key
71638db @groue v1.12.1
authored Mar 8, 2012
55 NSLog(@"GRMustache missing key: `%@` for %@", invocation.key, invocation.description);
86003ca @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
56 }
57 }
58 ```
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
59
71638db @groue v1.12.1
authored Mar 8, 2012
60 You'll get something like:
61
62 ```
63 GRMustache missing key: `items` for <GRMustacheInvocation: {{#items}} at line 23 in template .../foobar.mustache>
64 ```
65
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
66 Alter the template rendering
67 ----------------------------
68
69 The `returnValue` property of the *invocation* argument can be written. If you set it in `template:willRenderReturnValueOfInvocation:`, GRMustache will render the value you have provided.
70
08be4e8 @groue More precise wording about other Mustache implementations
authored Mar 5, 2012
71 **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
72
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
73
0bebc11 @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
74 ### A practical use: providing default values for missing keys
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
75
0132163 @groue experiment with GitHub Flavored Markdown
authored Mar 5, 2012
76 ```objc
77 - (void)template:(GRMustacheTemplate *)template willRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation
78 {
79 // When returnValue is nil, GRMustache could not find any value to render.
80 if (invocation.returnValue == nil) {
0bebc11 @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
81 invocation.returnValue = @"[DEFAULT]";
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
82 }
0132163 @groue experiment with GitHub Flavored Markdown
authored Mar 5, 2012
83 }
84 ```
79d2814 @groue GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
85
47684b7 @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
86 ### Even more practical uses: sample code
87
88 In the next guide, [sample_code.md](sample_code.md), you'll see the GRMustacheTemplateDelegate protocol in action.
86003ca @groue more GRMustacheTemplateDelegate documentation
authored Mar 5, 2012
89
18da0ef @groue Number formatting sample code
authored Mar 5, 2012
90 [up](../../../../GRMustache), [next](sample_code.md)
Something went wrong with that request. Please try again.