GRMustache

GRMustache is a flexible and production-ready implementation of Mustache templates for MacOS Cocoa and iOS.

GRMustache targets iOS down to version 4.3, MacOS down to 10.6 Snow Leopard (with or without garbage collection), and only depends on the Foundation framework.

February 3, 2014: GRMustache 6.9.1 is out. Release notes

Get release announcements and usage tips: follow @GRMustache on Twitter.

How To

1. Setup your Xcode project

You have three options, from the simplest to the hairiest:

• CocoaPods
• Static Library
• Compile the raw sources

2. Start rendering templates

#import "GRMustache.h"

One-liners:

// Renders "Hello Arthur!"
NSString *rendering = [GRMustacheTemplate renderObject:@{ @"name": @"Arthur" } fromString:@"Hello {{name}}!" error:NULL];

// Renders the `Profile.mustache` resource of the main bundle
NSString *rendering = [GRMustacheTemplate renderObject:user fromResource:@"Profile" bundle:nil error:NULL];

Reuse templates in order to avoid parsing the same template several times:

GRMustacheTemplate *template = [GRMustacheTemplate templateFromResource:@"Profile" bundle:nil error:nil];
rendering = [template renderObject:arthur error:NULL];
rendering = [template renderObject:barbara error:NULL];
rendering = ...

GRMustachio by Jonathan Mitchell is "A super simple, interactive GRMustache based application". It can help you design and test your templates.

Documentation

Mustache syntax

• http://mustache.github.io/mustache.5.html

Reference

• Reference: the GRMustache reference, automatically generated from inline documentation, for fun and profit, by appledoc.

Guides

Introduction:

• Introduction: a tour of the library features, and most common use cases.

Basics:

• Templates: how to load templates.
• Partials: decompose your templates into components named "partials".
• Templates Repositories: manage groups of templates.
• Runtime: how GRMustache renders your data.
• ViewModel: an overview of various techniques to feed templates.

Services:

• Configuration
• HTML vs. Text templates
• Standard Library: built-in candy, for your convenience.
• NSFormatter, NSNumberFormatter, NSDateFormatter, etc. Use them.

Hooks:

• Filters: {{ uppercase(name) }} et al.
• Rendering Objects: "Mustache lambdas", and more.
• Tag Delegates: observe and alter template rendering.
• Protected Contexts: protect some keys so that they always evaluate to the same value.

Mustache, and beyond:

• Compatibility: compatibility with other Mustache implementations, in details.

Sample code

Check the FAQ right below.

FAQ

• I get "unrecognized selector sent to instance" errors.

  Check that you have added the -ObjC option in the "Other Linker Flags" of your target (how to).

• is GRMustache thread-safe?

  Thread-safety of non-mutating methods is guaranteed. Thread-safety of mutating methods is not guaranteed.

• Is it possible to render array indexes? Customize first and last elements? Distinguish odd and even items, play fizzbuzz?

  Yes, yes, and yes.

• Is it possible to format numbers and dates?

  Yes. Use NSNumberFormatter and NSDateFormatter.

• Is it possible to pluralize/singularize strings?

  Yes. You have some sample code in issue #50. You may check @mattt's InflectorKit for actual inflection methods.

• Is it possible to write Handlebars-like helpers?

  Yes

• Is it possible to localize templates?

  Yes

• Is it possible to embed partial templates whose name is only known at runtime?

  Yes

• Does GRMustache provide any layout or template inheritance facility?

  Yes

• Is it possible to render a default value for missing keys?

  Yes

• Is it possible to disable HTML escaping?

  Yes

• What are those NSUndefinedKeyException?

  When GRMustache has to try several objects until it finds the one that provides a {{key}}, several NSUndefinedKeyException may be raised and caught. Those exceptions are part of the normal template rendering. You can be prevent them, though: see the Runtime Guide.

• Why does GRMustache need JRSwizzle?

  GRMustache does not need it, and does not swizzle anything unless you explicitly ask for it. [GRMustache preventNSUndefinedKeyExceptionAttack] swizzles NSObject's valueForUndefinedKey: in order to prevent NSUndefinedKeyException during template rendering. See the Runtime Guide for a detailed discussion.

What other people say

@JeffSchilling:

I'm loving grmustache

@basilshkara:

Oh man GRMustache saved my ass once again. Awesome lib.

@guiheneuf:

GRMustache filters extension saved us from great escaping PITAs. Thanks @groue.

@orj:

Thank fucking christ for decent iOS developers who ship .lib files in their Github repos. #GRMustache

@SebastienPeek

@issya should see the HTML template I built, pretty wicked. GRMustache is the best.

@mugginsoft

Using GRMustache (Cocoa) for template processing. Looks like a top quality library. Good developer and good units tests. Get it on GitHub.

@dannolan

okay GRMustache is the fucking daddy

@OldManKris

GRMustache is teh awesome. Nice to find an open-source library that is more pleasant to use than expected.

Who's using GRMustache

Open-source software

• bnickel/AMYServer: A mock server fully integrated with KIF-next.
• tomaz/appledoc: Objective-c code Apple style documentation set generator.
• Awful/Awful.app: Something Awful Forums browser for iOS
• stevestreza/Barista: A modular, embeddable web server for Objective-C.
• mapbox/mapbox-ios-sdk: MapBox iOS SDK, an open source alternative to MapKit.
• Objective-Cloud/OCFWeb: A small and imperfect web application framework written in Objective-C.
• as-cii/PdfReportKit: A library that generates a pdf report starting with HTML code.
• RESTmagic: RESTmagic is a framework for that framework you already deployed, your RESTFUL/RESTish api.
• Codeux/Textual: A lightweight IRC client for Mac OS X.
• CarterA/Tribo: Extremely fast static site generator written in Objective-C.

Closed-source software

• 1Password, a password manager that integrates directly with your web browser.
• AutoLib uses GRMustache and spullara/mustache.java for rendering an identical set of Mustache templates on iOS and Android.
• Bee: Bee is a desktop bug tracker for the Mac. It currently syncs with GitHub Issues, JIRA and FogBugz.
• CinéObs uses GRMustache for RSS feeds rendering.
• Fotopedia, the first collaborative photo encyclopedia.
• FunGolf GPS, a golf app with 3D maps.
• KosmicTask, an integrated scripting environment for OS X that supports more than 20 scripting languages.
• MyInvoice, an invoicing iOS app.
• Objective-Cloud, a service that runs your Objective-C code in the cloud.
• Servus can turn any file on your computer into a branded download page hosted on Dropbox.

Do you use GRMustache? Tweet me your story and your link.

Contribution wish-list

Please look for an open issue that smiles at you!

... And I wish somebody would review the non-native English of the documentation and guides.

Forking

Please fork. You'll learn useful information in the Forking Guide.

License

Released under the MIT License.