Browse files

guides wip

  • Loading branch information...
1 parent 1a1555f commit 6aa657e3e8a5311bc5d534867bec5ae01591d226 @groue committed Jan 25, 2012
View
4 README.md
@@ -46,7 +46,7 @@ GRMustache rendering is the combination of a template string and of an object th
Speaking of templates, GRMustache eats many kinds of them: raw strings, files, bundle resources. For more information, check [guides/templates.md](blob/master/guides/templates.md).
-Regarding the data objects, GRMustache fetches values with the standard Key-Value Coding `valueForKey:` method. Check [guides/rendering.md](blob/master/guides/rendering.md).
+Regarding the data objects, GRMustache fetches values with the standard Key-Value Coding `valueForKey:` method. Check [guides/runtime.md](blob/master/guides/runtime.md).
Mustache flavors
@@ -72,7 +72,7 @@ Features worth noting
Mustache has "lambda sections". These are sections that allow you to execute custom code, and implement nifty features like caching, filtering, whatever, on portions of your templates.
-Be sure to read GRMustache's take on the subject: [guides/rendering/helpers.md](blob/master/guides/rendering/helpers.md).
+Be sure to read GRMustache's take on the subject: [guides/runtime/helpers.md](blob/master/guides/runtime/helpers.md).
### Number and Date formatting
View
4 guides/date_formatting.md
@@ -1,8 +1,8 @@
+[up](../README.md), [next]()
+
Date formatting with GRMustacheDateFormatterHelper
==================================================
-[up](../README.md), [next]()
-
**This helper class allows you to format *all* dates in a section of your template.**
It does not belong the the core GRMustache code, and as such must be imported separately:
View
4 guides/embedding.md
@@ -1,8 +1,8 @@
+[up](../README.md), [next]()
+
Embedding GRMustache in your XCode project
==========================================
-[up](../README.md), [next]()
-
**TL;DR** Choose a static library in the `/lib` folder, and import the `/include/GRMustache.h` header.
---
View
4 guides/flavors.md
@@ -1,8 +1,8 @@
+[up](../README.md), [next]()
+
Mustache flavors
================
-[up](../README.md), [next]()
-
**TL;DR** Should you use compound key paths in your templates, you'd rather use the dot `"."` as a separator: `{{foo.bar}}`, and execute once, before any template processing, the following statement:
// Use genuine Mustache flavor
View
4 guides/forking.md
@@ -1,7 +1,7 @@
-# Note on forking
-
[up](../README.md), [next]()
+# Note on forking
+
After you have forked groue/GRMustache, you might want to change stuff, test, and then build the library.
You'll find below some useful information on each of those topics.
View
6 guides/number_formatting.md
@@ -1,8 +1,8 @@
+[up](../README.md), [next](date_formatting.md)
+
Number formatting with GRMustacheNumberFormatterHelper
======================================================
-[up](../README.md), [next](date_formatting.md)
-
**This helper class allows you to format *all* numbers in a section of your template.**
It does not belong the the core GRMustache code, and as such must be imported separately:
@@ -54,6 +54,6 @@ We just have to create two `GRMustacheNumberFormatterHelper` objects, provide th
// decimal: 0,5
[template renderObject:data];
-It is worth noting that the `GRMustacheNumberFormatterHelper` is implemented on top of public GRMustache APIs. Check the [code](../GRMustacheNumberFormatterHelper.m) for inspiration, and [guides/rendering/helpers.md](rendering/helpers.md) for more information on GRMustache's take on Mustache lambda sections.
+It is worth noting that the `GRMustacheNumberFormatterHelper` is implemented on top of public GRMustache APIs. Check the [code](../GRMustacheNumberFormatterHelper.m) for inspiration, and [guides/runtime/helpers.md](runtime/helpers.md) for more information on GRMustache's take on Mustache lambda sections.
[up](../README.md), [next](date_formatting.md)
View
16 guides/rendering.md → guides/runtime.md
@@ -1,7 +1,7 @@
-GRMustache rendering
-====================
+[up](../README.md), [next](runtime/context_stack.md)
-[up](../README.md), [next](rendering/context_stack.md)
+GRMustache runtime
+==================
GRMustache rendering is the combination of a template and of an object that will provide the data. This guide describes this interaction in detail.
@@ -20,9 +20,9 @@ You can thus provide rendering methods with NSDictionary instances, or custom ob
// "arthur"
[template renderObject:arthur];
-- [The context stack](rendering/context_stack.md) will cover Mustache sections
-- [Mustache loops](rendering/loops.md)
-- [Mustache booleans](rendering/booleans.md)
-- [Helpers](rendering/helpers.md)
+- [The context stack](runtime/context_stack.md) will cover Mustache sections and the KVC lookup mechanism.
+- [Mustache loops](runtime/loops.md)
+- [Mustache booleans](runtime/booleans.md)
+- [Helpers](runtime/helpers.md)
-[up](../README.md), [next](rendering/context_stack.md)
+[up](../README.md), [next](runtime/context_stack.md)
View
46 guides/rendering/booleans.md → guides/runtime/booleans.md
@@ -1,12 +1,25 @@
+[up](../runtime.md), [next](helpers.md)
+
# Booleans
-[up](../rendering.md), [next](helpers.md)
+**TL;DR** Sections render or not, depending on the boolean value of the object they are attached to. Generally speaking, all objects are considered true, except:
+
+- `nil`, and missing KVC keys
+- `[NSNull null]`
+- `[NSNumber numberWithBool:NO]`, aka `kCFBooleanFalse`
+- the empty string `@""`
+
+The most direct ways to provide sections with actual booleans are the explicit `[NSNumber numberWithBool:]` objects, and BOOL properties in your model objects.
+
+Beware zero (an NSNumber whose value is zero) is not considered false in GRMustache.
+
+---
Mustache sections can be controlled by booleans. For instance, the following template would render as an empty string, or as `"whistle"`, depending on the boolean value of the `pretty` key in the rendering context:
{{#pretty}}whistle{{/pretty}}
-We'll first talk about some simple cases. We'll then discuss important caveats. Don't miss them!
+We'll first talk about some simple cases. We'll then discuss caveats.
## Simple booleans: [NSNumber numberWithBool:]
@@ -51,26 +64,37 @@ For instance:
GRMustache considers as false the following values, and only those:
-- `nil`
+- `nil` and missing KVC keys
- `[NSNull null]`
- `[NSNumber numberWithBool:NO]`, aka `kCFBooleanFalse`
- the empty string `@""`
- // returns @"": nil is false
- [template renderObject:[NSDictionary dictionary]];
+Each of those renderings return the empty string:
- // returns @"": [NSNull null] is false
+ // @"foobar" has no `pretty` key
+ [template renderObject:@"foobar"];
+
+ // nil is false
+ [template renderObject:[NSDictionary dictionary]];
+
+ // [NSNull null] is false
[template renderObject:[NSDictionary dictionaryWithObject:[NSNull null]
forKey:@"pretty"]];
-
- // returns @"": [NSNumber numberWithBool:NO] is false
+
+ // [NSNumber numberWithBool:NO] is false
[template renderObject:[NSDictionary dictionaryWithObject:[NSNumber numberWithBool:NO]
forKey:@"pretty"]];
-
- // returns @"": @"" is false
+
+ // @"" is false
[template renderObject:[NSDictionary dictionaryWithObject:@""
forKey:@"pretty"]];
+Note that zero, as an explicit NSNumber whose value is zero, or as an int/float property, is not considered false in GRMustache:
+
+ // @"whistle"
+ [template renderObject:[NSDictionary dictionaryWithObject:[NSNumber numberWithInt:0]
+ forKey:@"pretty"]];
+
## Caveats
@@ -145,4 +169,4 @@ You may consider using the unbeloved C99 `bool` type. They can reliably control
- (bool)pretty;
@end
-[up](../rendering.md), [next](helpers.md)
+[up](../runtime.md), [next](helpers.md)
View
6 guides/rendering/context_stack.md → guides/runtime/context_stack.md
@@ -1,8 +1,8 @@
+[up](../runtime.md), [next](loops.md)
+
The context stack
=================
-[up](../rendering.md), [next](loops.md)
-
Mustache sections open new context
----------------------------------
@@ -54,5 +54,5 @@ The first will look for `bar` anywhere in the context stack, starting with the `
The latter ensures the `bar` key comes (or not) from the `foo` object.
-[up](../rendering.md), [next](loops.md)
+[up](../runtime.md), [next](loops.md)
View
10 guides/rendering/helpers.md → guides/runtime/helpers.md
@@ -1,13 +1,13 @@
+[up](../runtime.md), [next](../forking.md)
+
Helpers
=======
-[up](../rendering.md), [next](../forking.md)
-
GRMustache helpers allow you to implement "Mustache lambdas", that is to say have your own code executed when GRMustache renders a section such as `{{#name}}...{{/name}}`.
## Overview
-In GRMustache, the rendering is controlled by the data objects you provide to rendering methods. This topic is covered in detail in ([guides/rendering.md](rendering.md)).
+In GRMustache, the rendering is controlled by the data objects you provide to rendering methods. This topic is covered in detail in ([guides/runtime.md](runtime.md)).
The principles covered here will thus always be the same: it's a matter of providing the rendering methods of GRMustache with data objects which have code attached to specific template keys.
@@ -27,7 +27,7 @@ For the purpose of demonstration, we'll implement a helper that translates, via
If the context used for mustache rendering implements the `localizeSection:withContext:` selector (generally, a method whose name is the name of the section, to which you append `Section:withContext:`), then this method will be called when rendering the section.
-The choice of the class that should implement this selector is up to you, as long as it can be reached when rendering the template, just as regular values (see ([guides/rendering.md](rendering.md))).
+The choice of the class that should implement this selector is up to you, as long as it can be reached when rendering the template, just as regular values (see ([guides/runtime.md](runtime.md))).
For instance, let's focus on the following template snippet:
@@ -215,4 +215,4 @@ You may implement debugging sections:
return nil; // don't render anything
});
-[up](../rendering.md), [next](../forking.md)
+[up](../runtime.md), [next](../forking.md)
View
6 guides/rendering/loops.md → guides/runtime/loops.md
@@ -1,8 +1,8 @@
+[up](../runtime.md), [next](booleans.md)
+
Mustache loops
==============
-[up](../rendering.md), [next](booleans.md)
-
Mustache sections that are provided with an enumerable object will be rendered once for each item in it.
Those are all objects conforming to the NSFastEnumeration protocol, but NSDictionary. The most obvious enumerable is NSArray.
@@ -27,4 +27,4 @@ For instance, the following template can render `{ items: ['ham', 'jam'] }`.
{{/items}}
</ul>
-[up](../rendering.md), [next](booleans.md)
+[up](../runtime.md), [next](booleans.md)

0 comments on commit 6aa657e

Please sign in to comment.