Skip to content
Browse files

Collection Indexes Sample Code update

  • Loading branch information...
1 parent 85e16b1 commit 080330045a7f86e9324e7c61a8a5fb9abeae8ce6 @groue committed Oct 30, 2012
Showing with 32 additions and 54 deletions.
  1. +32 −54 Guides/sample_code/indexes.md
View
86 Guides/sample_code/indexes.md
@@ -1,12 +1,12 @@
[up](../../../../tree/master/Guides/sample_code), [next](localization.md)
-Indexes
-=======
+Collection Indexes
+==================
In a genuine Mustache way
-------------------------
-Mustache is a simple template language. Its [specification](https://github.com/mustache/spec) does not provide any built-in access to loop indexes. It does not provide any way to render a section at the beginning of the loop, and another section at the end. It does not help you render different sections for odd and even indexes.
+Mustache is a simple template language. Its [specification](https://github.com/mustache/spec) does not provide any built-in access to collection indexes. It does not provide any way to render a section at the beginning of a loop, and another section at the end. It does not help you render different sections for odd and even indexes.
If your goal is to design your templates so that they are compatible with [other Mustache implementations](https://github.com/defunkt/mustache/wiki/Other-Mustache-implementations), the best way to render indices and provide custom looping logic is to have each of your data objects provide with its index, regardless of how tedious it may be for you to prepare the rendered data.
@@ -24,9 +24,9 @@ You can have Mustache templates render positional keys like `position` or `isFir
So check again the genuine Mustache way, above. Or keep on reading, now that you are warned.
-### The template
+### The rendering
-Below we'll implement the special keys `position`, `isFirst`, and `isOdd`. We'll render the following template:
+Below we'll implement the special keys `position`, `isFirst`, and `isOdd`:
`Document.mustache`:
@@ -38,42 +38,6 @@ Below we'll implement the special keys `position`, `isFirst`, and `isOdd`. We'll
{{/ withPosition(people) }}
</ul>
-Final rendering:
-
- <ul>
- <li class="odd first">
- 1:Alice
- </li>
- <li class=" ">
- 2:Bob
- </li>
- <li class="odd ">
- 3:Craig
- </li>
- </ul>
-
-
-Our people array will be a plain array filled with plain people who don't know anything but their name. The support for the special positional keys will be brought by the `withPosition` [filter](../filters.md).
-
-### The rendering
-
-Let's first assume that the filter is already implemented, ready to be used. It comes as a `PositionFilter` class that is documented this way:
-
-```objc
-/**
- * A GRMustache filter that render its array argument with the extra following
- * keys defined for each item:
- *
- * - position: returns the 1-based index of the item
- * - isOdd: returns YES if the position of the item is odd
- * - isFirst: returns YES if the item is at position 1
- */
-@interface PositionFilter : NSObject<GRMustacheFilter>
-@end
-```
-
-Well, it looks quite a good fit for our task. We have everything we need to render our template:
-
`Render.m`:
```objc
@@ -92,18 +56,33 @@ NSString *rendering = [GRMustacheTemplate renderObject:data
error:NULL];
```
-### The filter implementation
+Final rendering:
+
+ <ul>
+ <li class="odd first">
+ 1:Alice
+ </li>
+ <li class=" ">
+ 2:Bob
+ </li>
+ <li class="odd ">
+ 3:Craig
+ </li>
+ </ul>
+
+
+### PositionFilter implementation
You may just skip the rest of this document, and [download the `PositionFilter` class](../../../../tree/master/Guides/sample_code/indexes). It should be trivial to adapt, should you need the `isLast` property, for example.
-Let's now implement this nifty `PositionFilter` class.
+Let's see how it is implemented.
-We have already seen above its declaration: it's simply a class that conforms to the GRMustacheFilter protocol:
+Due to the parenthesis in the `withPosition(people)` expressio, we know that it is a [filter](../filters.md), an object that conforms to the `GRMustacheFilter` protocol:
```objc
/**
- * A GRMustache filter that render its array argument with the extra following
- * keys defined for each item:
+ * A filter that renders its array argument with the extra following keys
+ * defined for each item:
*
* - position: returns the 1-based index of the item
* - isOdd: returns YES if the position of the item is odd
@@ -113,11 +92,11 @@ We have already seen above its declaration: it's simply a class that conforms to
@end
```
-As such, it must implement the `transformedValue:` method, that returns the result of the filter. That result will perform a custom rendering of its array argument.
+The protocol requires the `transformedValue:` method, that returns the result of the filter.
-You provide custom rendering with objects that conform to the `GRMustacheRendering` protocol (see the [Rendering Objects Guide](../rendering_objects.md)). Our custom rendering object will render the section tag as many times as it has items, extending the [context stack](../runtime.md) with both a dictionary containing the special keys, and the array items that will provide the `name` key.
+Since we need a custom rendering of the array, the result of the filter will conform to the `GRMustacheRendering` protocol (see the [Rendering Objects Guide](../rendering_objects.md)).
-Actually, writing [filters](../filters.md) that return [rendering objects](../rendering_objects.md) lead to code that is pretty close to the [Handlebars.js block helpers](http://handlebarsjs.com/block_helpers.html). You may enjoy comparing the code below to the [`each_with_index` Handlebars helper](https://gist.github.com/1048968).
+Rendering objects take full responsability of their rendering. Our will render the section tag as many times as the array has items, extending the [context stack](../runtime.md) with both a dictionary containing the special keys, and the array items that will provide the `name` key.
```objc
@implementation PositionFilter
@@ -130,11 +109,9 @@ Actually, writing [filters](../filters.md) that return [rendering objects](../re
- (id)transformedValue:(NSArray *)array
{
- /**
- * We want to provide custom rendering of the array.
- *
- * So let's provide an object that does custom rendering.
- */
+ // We want to provide custom rendering of the array.
+ //
+ // So let's return an object that does custom rendering.
return [GRMustache renderingObjectWithBlock:^NSString *(GRMustacheTag *tag, GRMustacheContext *context, BOOL *HTMLSafe, NSError *__autoreleasing *error)
{
@@ -172,6 +149,7 @@ Actually, writing [filters](../filters.md) that return [rendering objects](../re
@end
```
+Writing [filters](../filters.md) that return [rendering objects](../rendering_objects.md) lead to code that is pretty close to the [Handlebars.js block helpers](http://handlebarsjs.com/block_helpers.html). You may enjoy comparing the code above to the [`each_with_index` Handlebars helper](https://gist.github.com/1048968).
**[Download the code](../../../../tree/master/Guides/sample_code/indexes)**

0 comments on commit 0803300

Please sign in to comment.
Something went wrong with that request. Please try again.