Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 189 lines (137 sloc) 6.313 kB
2e61bf9 @groue Fix internal guide links
authored
1 [up](../../../../tree/master/Guides/sample_code), [next](indexes.md)
18da0ef @groue Number formatting sample code
authored
2
3 Number formatting
4 =================
5
0dbc221 @groue Rewritten number formatting guide, so that it uses filters.
authored
6 For the purpose of demonstration, we'll render the value 0.5 as a *raw* number, as a percentage, and as a *decimal*. For instance, on a French system, we'll get the following output:
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
7
8 raw: 0.5
9 percent: 50 %
10 decimal: 0,5
11
12
18da0ef @groue Number formatting sample code
authored
13 In a genuine Mustache way
14 -------------------------
15
16 Mustache is a simple template language. This is why there are so many [other Mustache implementations](https://github.com/defunkt/mustache/wiki/Other-Mustache-implementations).
17
18 If your goal is to design your templates so that they are compatible with those, the best way to format numbers is to have your data objects provide those formatted numbers.
19
79020b4 @groue number_formatting.md and indexes.md consistency
authored
20 ### 1st genuine Mustache technique: NSDictionary
18da0ef @groue Number formatting sample code
authored
21
22 Let's render the simple template:
23
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
24 raw: {{ value }}
25 percent: {{ percent }}
26 decimal: {{ decimal }}
18da0ef @groue Number formatting sample code
authored
27
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
28 It's quite easy to put numbers and formatted numbers in a dictionary:
18da0ef @groue Number formatting sample code
authored
29
30 ```objc
fae0cef @groue Rewritten number formatting guide, so that it uses filters.
authored
31 // The raw number
8dcc514 @groue Use Objective-C literals in guides
authored
32 NSNumber *value = @0.5:
18da0ef @groue Number formatting sample code
authored
33
fae0cef @groue Rewritten number formatting guide, so that it uses filters.
authored
34 // NSNumberFormatter objects knows how to format numbers
18da0ef @groue Number formatting sample code
authored
35 NSNumberFormatter *percentNumberFormatter = [[NSNumberFormatter alloc] init];
36 percentNumberFormatter.numberStyle = kCFNumberFormatterPercentStyle;
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
37 NSString *percent = [numberFormatter stringFromNumber:value];
38
39 NSNumberFormatter *decimalNumberFormatter = [[NSNumberFormatter alloc] init];
40 decimalNumberFormatter.numberStyle = kCFNumberFormatterDecimalStyle;
41 NSString *decimal = [numberFormatter stringFromNumber:value];
18da0ef @groue Number formatting sample code
authored
42
f5f8e18 @groue Rewritten number formatting guide, so that it uses filters.
authored
43 // Render "raw: 0.5, percent: 50 %, decimal: 0,5"
8dcc514 @groue Use Objective-C literals in guides
authored
44 NSDictionary *dictionary = @{
45 @"value": value,
46 @"percent": percent,
47 @"decimal": decimal
48 };
18da0ef @groue Number formatting sample code
authored
49 NSString *rendering = [template renderObject:dictionary];
50 ```
51
79020b4 @groue number_formatting.md and indexes.md consistency
authored
52 ### 2nd genuine Mustache technique: specific properties
18da0ef @groue Number formatting sample code
authored
53
35162b7 @groue Hard wrap documentation to 80 columns
authored
54 Often, data comes from your model objects, not from a hand-crafted NSDictionary.
18da0ef @groue Number formatting sample code
authored
55
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
56 In this case, the best option is to declare a category on your model object, and implement specific keys that will output the formatted numbers:
18da0ef @groue Number formatting sample code
authored
57
58 ```objc
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
59 @interface Model
60 @property float value; // the original property provided by the model
61 @end
62
63 @interface Model(GRMustache)
18da0ef @groue Number formatting sample code
authored
64 @property (readonly) NSString *percent;
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
65 @property (readonly) NSString *decimal;
18da0ef @groue Number formatting sample code
authored
66 @end
67
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
68 @implementation Model(GRMustache)
18da0ef @groue Number formatting sample code
authored
69 - (NSString *)percent
70 {
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
71 NSNumberFormatter *numberFormatter = [[NSNumberFormatter alloc] init];
72 numberFormatter.numberStyle = kCFNumberFormatterPercentStyle;
73 return [numberFormatter stringFromNumber:[NSNumber numberWithFloat:self.value]];
74 }
75
76 - (NSString *)decimal
77 {
78 NSNumberFormatter *numberFormatter = [[NSNumberFormatter alloc] init];
79 numberFormatter.numberStyle = kCFNumberFormatterDecimalStyle;
80 return [numberFormatter stringFromNumber:[NSNumber numberWithFloat:self.value]];
18da0ef @groue Number formatting sample code
authored
81 }
82 @end
83 ```
84
85 You would then render normally:
86
87 ```objc
f5f8e18 @groue Rewritten number formatting guide, so that it uses filters.
authored
88 // Render "raw: 0.5, percent: 50 %, decimal: 0,5"
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
89 Model *model = ...
90 model.value = 0.5;
18da0ef @groue Number formatting sample code
authored
91 NSString *rendering = [template renderObject:model];
92 ```
93
9634de6 @groue Mention tag delegates as another way to format numbers
authored
94 Tag delegates
95 -------------
96
97 [Tag delegates](delegate.md) allow all numbers in a section to be formatted. For instance, in the following template, all numbers would be formatted as currencies:
98
99 {{#currency}}
100 {{#items}}
101 {{name}}: {{price}}
102 {{/items}}
103 total: {{total}}
104 taxes: {{taxes}}
105 {{/currency}}
106
107 You'll find the code in the [Tag Delegates Guide](delegate.md#altering-the-rendering-of-tags-in-a-section).
108
109 Filters
110 -------
18da0ef @groue Number formatting sample code
authored
111
c1aaf13 @groue More links from guides to sample projects
authored
112 **[Download the code](../../../../tree/master/Guides/sample_code/number_formatting)**
3f50ab0 @groue Links to sample code projects hosted at https://github.com/groue/GRMu…
authored
113
18da0ef @groue Number formatting sample code
authored
114 You may ask yourself, is it worth declaring dozens of stub properties just for formatting numbers?
115
9634de6 @groue Mention tag delegates as another way to format numbers
authored
116 [Filters](../filters.md) are quite helpful, here. However, **it may be impossible for [other Mustache implementations](https://github.com/defunkt/mustache/wiki/Other-Mustache-implementations) to produce the same rendering.**
18da0ef @groue Number formatting sample code
authored
117
118 So check again the genuine Mustache way, above. Or keep on reading, now that you are warned.
119
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
120 Let's first rewrite our template so that it uses filters:
18da0ef @groue Number formatting sample code
authored
121
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
122 raw: {{ value }}
123 percent: {{ percent(value) }}
124 decimal: {{ decimal(value) }}
18da0ef @groue Number formatting sample code
authored
125
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
126 After we have told GRMustache how the `percent` and `decimal` filters should process their input, we will be releived from the need to prepare our data before it is rendered: no more adding of specific keys in a dictionary, no more declaration of a category on our models.
18da0ef @groue Number formatting sample code
authored
127
128 ```objc
129 - (NSString *)render
130 {
131 /**
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
132 * Our template wants to render floats in various formats: raw, or formatted
133 * as percentage, or formatted as decimal.
18da0ef @groue Number formatting sample code
authored
134 */
a5c96e1 @groue Number Formatting Sample Code update
authored
135
38d683c @groue Filters and empty closing section {{/}} are now accepted without the …
authored
136 NSString *templateString = @"raw: {{ value }}\n"
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
137 @"percent: {{ percent(value) }}\n"
138 @"decimal: {{ decimal(value) }}";
139 GRMustacheTemplate *template = [GRMustacheTemplate templateFromString:templateString error:NULL];
18da0ef @groue Number formatting sample code
authored
140
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
141 /**
a5c96e1 @groue Number Formatting Sample Code update
authored
142 * Let's define the `percent` and `decimal` filters:
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
143 *
144 * Filters have to be objects that conform to the GRMustacheFilter protocol.
145 * The easiest way to build one is to use the
146 * [GRMustacheFilter filterWithBlock:] method.
147 *
148 * The formatting itself is done by our friend NSNumberFormatter.
149 */
150
18da0ef @groue Number formatting sample code
authored
151 NSNumberFormatter *percentNumberFormatter = [[NSNumberFormatter alloc] init];
152 percentNumberFormatter.numberStyle = kCFNumberFormatterPercentStyle;
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
153
18da0ef @groue Number formatting sample code
authored
154 NSNumberFormatter *decimalNumberFormatter = [[NSNumberFormatter alloc] init];
155 decimalNumberFormatter.numberStyle = kCFNumberFormatterDecimalStyle;
156
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
157 id percentFilter = [GRMustacheFilter filterWithBlock:^id(id value) {
158 return [percentNumberFormatter stringFromNumber:value];
159 }];
18da0ef @groue Number formatting sample code
authored
160
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
161 id decimalFilter = [GRMustacheFilter filterWithBlock:^id(id value) {
162 return [decimalNumberFormatter stringFromNumber:value];
163 }];
18da0ef @groue Number formatting sample code
authored
164
165
166 /**
a5c96e1 @groue Number Formatting Sample Code update
authored
167 * We use a NSDictionary for storing our data, but you can use any
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
168 * other KVC-compliant container.
35162b7 @groue Hard wrap documentation to 80 columns
authored
169 */
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
170
a5c96e1 @groue Number Formatting Sample Code update
authored
171 id data = @{
8dcc514 @groue Use Objective-C literals in guides
authored
172 @"percent": percentFilter,
a5c96e1 @groue Number Formatting Sample Code update
authored
173 @"decimal": decimalFilter,
174 @"value": @(0.5),
8dcc514 @groue Use Objective-C literals in guides
authored
175 };
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
176
459f57b @groue v4.1.0
authored
177
35162b7 @groue Hard wrap documentation to 80 columns
authored
178 /**
a5c96e1 @groue Number Formatting Sample Code update
authored
179 * Render.
35162b7 @groue Hard wrap documentation to 80 columns
authored
180 */
a68a579 @groue Rewritten number formatting guide, so that it uses filters.
authored
181
a5c96e1 @groue Number Formatting Sample Code update
authored
182 return [template renderObject:data error:NULL];
18da0ef @groue Number formatting sample code
authored
183 }
184 ```
185
c1aaf13 @groue More links from guides to sample projects
authored
186 **[Download the code](../../../../tree/master/Guides/sample_code/number_formatting)**
187
9634de6 @groue Mention tag delegates as another way to format numbers
authored
188
2e61bf9 @groue Fix internal guide links
authored
189 [up](../../../../tree/master/Guides/sample_code), [next](indexes.md)
Something went wrong with that request. Please try again.