Permalink
Browse files

guides

  • Loading branch information...
groue committed Jan 24, 2012
1 parent 68f442c commit 4f1625f451ffda682529326c5f2e8365b1497b5b
View
824 README.md

Large diffs are not rendered by default.

Oops, something went wrong.
View
@@ -0,0 +1,10 @@
+Date formatting with GRMustacheDateFormatterHelper
+==================================================
+
+**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:
+
+ #import "GRMustacheDateFormatterHelper.h"
+
+Read [guides/number_formatting.md](number_formatting.md) documentation, because the principles are the same. You'll just provide a `NSDateFormatter` instead of a `NSNumberFormatter`.
View
@@ -0,0 +1,33 @@
+Embedding GRMustache in your XCode project
+==========================================
+
+GRMustache ships as a static library and a header file, and only depends on the Foundation.framework.
+
+The `GRMustache.h` header file is located into the `/include` folder at the root of the GRMustache repository. Add it to your project.
+
+You'll have next to choose a static library among those located in the `/lib` folder:
+
+- `libGRMustache1-ios3.a`
+- `libGRMustache1-ios4.a`
+- `libGRMustache1-macosx10.6.a`
+
+`libGRMustache1-ios3.a` targets iOS3+, and include both device and simulator architectures (i386 armv6 armv7). This means that this single static library allows you to run GRMustache on both simulator and iOS devices.
+
+`libGRMustache1-ios4.a` targets iOS4+, and include both device and simulator architectures (i386 armv6 armv7). On top of all the APIs provided by `libGRMustache1-ios3.a`, you'll find blocks and NSURL* APIs in this version of the lib.
+
+`libGRMustache1-macosx10.6.a` targets MaxOSX 10.6+. It includes both 32 and 64 bits architectures (i386 x86_64), and the full set of GRMustache APIs.
+
+Other headers
+-------------
+
+Generally, importing the `GRMustache.h` header provides you with all the core GRMustache features.
+
+However, you will have to explicitely import:
+
+- `GRMustacheTemplateLoader_protected.h`
+
+ when you want to subclass `GRMustacheTemplateLoader`, and provide your own template loading strategy. See [guides/template_loaders.md](template_loaders.md)
+
+- `GRMustacheNumberFormatterHelper.h` and `GRMustacheDateFormatterHelper.h`
+
+ when you want to use these helpers in order to format your numbers and dates. See [guides/number_formatting.md](number_formatting.md) and [guides/date_formatting.md](date_formatting.md)
View
@@ -0,0 +1,83 @@
+Mustache flavors
+================
+
+GRMustache ships with two concurrent interpretations of Mustache templates:
+
+- genuine Mustache, as described by the [Mustache specification v1.1.2](https://github.com/mustache/spec)
+- [Handlebars.js](https://github.com/wycats/handlebars.js)
+
+How to choose a flavor
+----------------------
+
+The only difference so far between the two flavors implementation lies in the syntax for key paths: when genuine Mustache reads `{{foo.bar.baz}}`, Handlebars reads `{{foo/bar/baz}}`, and even `{{../foo/bar/baz}}`.
+
+If your templates do not use compound key paths, you can ignore this guide entirely.
+
+### Application-wide flavor
+
+If all of the templates processed by your application belong to the same flavor, you may consider setting the application-wide flavor with one of the following statement, prior to any template processing:
+
+ // Use genuine Mustache flavor
+ [GRMustache setDefaultTemplateOptions:GRMustacheTemplateOptionMustacheSpecCompatibility];
+
+ // Use Handlebars flavor (the default)
+ [GRMustache setDefaultTemplateOptions:GRMustacheTemplateOptionNone];
+
+Despite the fact that GRMustache defaults to Handlebars flavor, we encourage you writing your templates in genuine Mustache.
+
+### Per-template flavor
+
+Your application can process templates of different flavors:
+
+All GRMustache methods that are involved in template parsing have sister methods that take options as an argument.
+
+- `+[GRMustacheTemplate renderObject:fromString:error:]`
+- `+[GRMustacheTemplate renderObject:fromString:options:error:]`
+- `+[GRMustacheTemplate parseResource:bundle:error:]`
+- `+[GRMustacheTemplate parseResource:bundle:options:error:]`
+- `+[GRMustacheTemplateLoader templateLoaderWithBaseURL:]`
+- `+[GRMustacheTemplateLoader templateLoaderWithBaseURL:options:]`
+- etc.
+
+The methods with explicit options will process the template as expected:
+
+ // Use genuine Mustache flavor
+ [GRMustacheTemplate renderObject:...
+ fromString:...
+ options:GRMustacheTemplateOptionMustacheSpecCompatibility
+ error:...];
+
+ // Use Handlebars flavor
+ [GRMustacheTemplate renderObject:...
+ fromString:...
+ options:GRMustacheTemplateOptionNone
+ error:...];
+
+The methods with no explicit option use the default one set by `+[GRMustache setDefaultTemplateOptions:]`.
+
+Note that once a template has been parsed, you can not render it in another flavor:
+
+ // Parse a Handlebars template
+ GRMustacheTemplate *template = [GRMustacheTemplate parseResource:...
+ bundle:...
+ options:GRMustacheTemplateOptionNone
+ error:...]`
+
+ // Renders a Handlebars template (there is no `renderObject:options:` method):
+ [template renderObject:...]
+
+Specifications coverage
+-----------------------
+
+### Genuine Mustache
+
+GRMustache has full coverage of [Mustache specification v1.1.2](https://github.com/mustache/spec), **except for whitespace management**.
+
+That is to say, each character of your templates will be rendered as is, whitespace included.
+
+### Handlebars
+
+[Handlebars.js](https://github.com/wycats/handlebars.js) has introduced many nifty features.
+
+Actually, GRMustache implements a single one: the syntax for key paths `{{foo/bar/baz}}` and `{{../foo/bar/baz}}`.
+
View
No changes.
View
No changes.
@@ -0,0 +1,55 @@
+Number formatting with GRMustacheNumberFormatterHelper
+======================================================
+
+**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:
+
+ #import "GRMustacheNumberFormatterHelper.h"
+
+Usage
+-----
+
+For instance, given the following template:
+
+ raw: {{float}}
+
+ {{#percent_format}}
+ percent: {{float}}
+ {{/percent_format}}
+
+ {{#decimal_format}}
+ decimal: {{float}}
+ {{/decimal_format}}
+
+The float value would be displayed as a percentage in the `percent_format` section, and as a decimal in the `decimal_format` section.
+
+We just have to create two `GRMustacheNumberFormatterHelper` objects, provide them with `NSNumberFormatter` instances, and attach them to the section names:
+
+ #import "GRMustacheNumberFormatterHelper.h"
+
+ // The percent formatter, and helper:
+ NSNumberFormatter percentNumberFormatter = [[[NSNumberFormatter alloc] init] autorelease];
+ percentNumberFormatter.numberStyle = kCFNumberFormatterPercentStyle;
+ id percentHelper = [GRMustacheNumberFormatterHelper helperWithNumberFormatter:percentNumberFormatter];
+
+ // The decimal formatter, and helper:
+ NSNumberFormatter decimalNumberFormatter = [[[NSNumberFormatter alloc] init] autorelease];
+ decimalNumberFormatter.numberStyle = kCFNumberFormatterDecimalStyle;
+ id decimalHelper = [GRMustacheNumberFormatterHelper helperWithNumberFormatter:decimalNumberFormatter];
+
+ // The rendered data:
+ NSNumber *float = [NSNumber numberWithFloat:0.5];
+ NSDictionary *data = [NSDictionary dictionaryWithObjectsAndKeys:
+ percentHelper, @"percent_format",
+ decimalHelper, @"decimal_format",
+ float, @"float",
+ nil];
+
+ // The final rendering (on a French system):
+ // raw: 0.5
+ // percent: 50 %
+ // 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/helpers.md](helpers.md) for more information on GRMustache's take on Mustache lambda sections.
View
No changes.
View
No changes.

0 comments on commit 4f1625f

Please sign in to comment.