Permalink
Browse files

guides wip

  • Loading branch information...
1 parent acb8902 commit 1a1555fda40ead2f6c9ba2695a89fbe9a0bd9276 @groue committed Jan 25, 2012
View
@@ -39,14 +39,14 @@ GRMustache rendering is the combination of a template string and of an object th
NSString *templateString = @"Hello {{name}}!";
Person *arthur = [Person personWithName:@"Arthur"];
- // return "Hello Arthur!"
+ // Returns "Hello Arthur!"
[GRMustacheTemplate renderObject:arthur
fromString:templateString
error:NULL];
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/runtime.md](blob/master/guides/runtime.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).
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/helpers.md](blob/master/guides/helpers.md).
+Be sure to read GRMustache's take on the subject: [guides/rendering/helpers.md](blob/master/guides/rendering/helpers.md).
### Number and Date formatting
@@ -1,10 +1,14 @@
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:
#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`.
+
+[up](../README.md), [next]()
View
@@ -1,6 +1,12 @@
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.
+
+---
+
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.
@@ -11,7 +17,7 @@ You'll have next to choose a static library among those located in the `/lib` fo
- `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-ios3.a` targets iOS3+, and include both device and simulator architectures (i386 armv6 armv7). 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.
@@ -30,4 +36,6 @@ However, you will have to explicitely import:
- `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)
+ 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)
+
+[up](../README.md), [next]()
View
@@ -1,6 +1,15 @@
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
+ [GRMustache setDefaultTemplateOptions:GRMustacheTemplateOptionMustacheSpecCompatibility];
+
+---
+
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)
@@ -9,25 +18,25 @@ GRMustache ships with two concurrent interpretations of Mustache templates:
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}}`.
+The only difference so far between the two flavors implementation lies in the syntax for key paths: 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.
+If you are designing new templates from scratch, we encourage you writing your templates in the genuine Mustache flavor. Beware that GRMustache defaults to Handlebars: keep on reading.
+
### 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:
+If all of the templates processed by your application belong to the same flavor, 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:
+Your application may have to process templates of different flavors.
All GRMustache methods that are involved in template parsing have sister methods that take options as an argument.
@@ -81,3 +90,4 @@ That is to say, each character of your templates will be rendered as is, whitesp
Actually, GRMustache implements a single one: the syntax for key paths `{{foo/bar/baz}}` and `{{../foo/bar/baz}}`.
+[up](../README.md), [next]()
View
@@ -0,0 +1,77 @@
+# Note on forking
+
+[up](../README.md), [next]()
+
+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.
+
+## Change GRMustache
+
+There are two projects: one for MacOS, and one for iOS: `GRMustache1-macosx.xcodeproj` and `GRMustache1-ios.xcodeproj`. When XCode allows for multi-platform projects, there will be a single one :-) (addendum: it looks like XCode 4.2 allows for that, stay tuned).
+
+Objective-C files that make GRMustache are stored in the `Classes` folder.
+
+When a file is added or removed from the `Classes` folder, both projects are updated.
+
+When a header file is added to the `Classes` folder, the "Copy headers" build phase of the three targets (one for the MacOS project, two for the iOS project) are updated accordingly. The set of public headers of all three targets are the same.
+
+Headers are splitted in two categories:
+
+- public headers
+- private headers
+
+### Public headers
+
+Public headers must contain only declarations for APIs that are exposed to the GRMustache users. They must not import or include any private header.
+
+Methods and functions declared in public headers must be decorated with the macros defined in `Classes/GRMustacheAvailabilityMacros.h`. Check existing public headers for inspiration.
+
+### Private headers
+
+Private headers have names ending in `_private.h`. They must not import or include any public header. The set of public APIs must be duplicated in both public and private headers.
+
+## Test GRMustache
+
+There are two kinds of tests, all stored in the `Tests` folder.
+
+- tests of private APIs
+- tests of public APIs
+
+When a file is added or removed from the `Tests` folder, both `GRMustache1-macosx.xcodeproj` and `GRMustache1-ios.xcodeproj` projects are updated.
+
+### Tests of private APIs
+
+Tests of private internals are stored in the `Tests/Private` folder, and are all subclasses of `GRMustachePrivateAPITest`.
+
+The implementation files of those tests must not include any public header.
+
+### Tests of public APIS
+
+Tests of public GRMustache API are versionned: the `Tests/v1.0` folder contains tests for features introduced in the version 1.0 of the library. `Tests/v1.1` contains tests for the version 1.1, etc.
+
+Those tests are all subclasses of `GRMustachePublicAPITest`. Their implementation files must not include any private header.
+
+You will use the macros defined in `Classes/GRMustacheAvailabilityMacros.h`. They help the tests acheiving three goals:
+
+- use only APIs that are available in the GRMustache version they test against,
+- emit deprecation warning when they use deprecated GRMustache APIs,
+- help GRMustache achieve the full backward compatibility claimed by the [APR](http://apr.apache.org/versioning.html) compliance.
+
+For instance, all header files for public API tests in `Tests/v1.4` begin with:
+
+ #define GRMUSTACHE_VERSION_MIN_REQUIRED GRMUSTACHE_VERSION_1_4
+ #define GRMUSTACHE_VERSION_MAX_REQUIRED GRMUSTACHE_VERSION_1_4
+ #import "GRMustachePublicAPITest.h"
+
+When you add a test for a specific behavior of a public API, make sure you place it in the version that introduced this behavior (check the release notes).
+
+## Building
+
+The GRMustache "product" itself is made of both the `lib` and `include` folders.
+
+The XCode GUI can not build them. Instead, you'll issue the following command in the terminal:
+
+ $ make clean && make
+
+[up](../README.md), [next]()
View
No changes.
View
No changes.
@@ -1,6 +1,8 @@
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:
@@ -24,7 +26,7 @@ For instance, given the following template:
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:
+We just have to create two `GRMustacheNumberFormatterHelper` objects, provide them with `NSNumberFormatter` instances, and attach them to the sections names:
#import "GRMustacheNumberFormatterHelper.h"
@@ -52,4 +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/helpers.md](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/rendering/helpers.md](rendering/helpers.md) for more information on GRMustache's take on Mustache lambda sections.
+
+[up](../README.md), [next](date_formatting.md)
View
@@ -0,0 +1,28 @@
+GRMustache rendering
+====================
+
+[up](../README.md), [next](rendering/context_stack.md)
+
+GRMustache rendering is the combination of a template and of an object that will provide the data. This guide describes this interaction in detail.
+
+Generally speaking, GRMustache will look for values in your data objects through the standard Key-Value Coding `valueForKey:` method.
+
+You can thus provide rendering methods with NSDictionary instances, or custom objects with properties or methods whose name match the keys in the template tags.
+
+ GRMustacheTemplate *template = [GRMustacheTemplate parseString:@"{{name}}" error:NULL];
+
+ NSDictionary *dictionary = [NSDictionary dictionaryWithObject:@"dictionary" forKey:@"name"];
+ Person *arthur = [Person personWithName:@"arthur"];
+
+ // "dictionary"
+ [template renderObject:dictionary];
+
+ // "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)
+
+[up](../README.md), [next](rendering/context_stack.md)
Oops, something went wrong.

0 comments on commit 1a1555f

Please sign in to comment.