MGTemplateEngine – Templates with Cocoa
MGTemplateEngine is a native Cocoa system for generating text output based on templates and data. It’s a close cousin of systems like Smarty, FreeMarker, Django’s template language, and so on.
It’s ideal for Cocoa apps needing to generate text output using variable-substitution (with looping and/or conditional logic), including creating HTML pages (or for apps with WebKit-based UIs), generating invoices or other printable templates, mail merge, data export or any number of other things. It’s also great (in combination with WebKit) for letting your users create themes/styles for your application.
Here’s a sample template, and the corresponding sample output (with appropriate variables fed to the template engine).
The default syntax for markers (functions or language-constructs) is:
{% for 1 to 5 %} foo {% /for %}
and the default syntax for variables/expressions is:
{{ foo.bar | uppercase }}
The pipe-character indicates a filter is being applied; i.e. the value of “foo.bar” will then be fed to the “uppercase” filter before being displayed. You can apply filters to markers as well as variables.
The marker, variable and filter delimiters are completely customizable, so you’re not stuck with the defaults if you prefer different syntax. You can also write your own markers (language constructs/functions), filters (data-formatting functions) and even your own matchers (advanced; see documentation).
MGTemplateEngine offers the following features:
- Native Cocoa implementation. It doesn’t use the Scripting Bridge or any external runtimes/frameworks, and as such the core engine itself has no requirements other than Mac OS X Leopard.
- Very customizable. It’s very easy to define new markers (like functions or language-constructs) and new filters (data-formatting capabilities). You can also freely change the syntax of the markers and expressions to suit your own tastes, or to mimic your favorite other templating system.
- Delegate system to keep you informed. MGTemplateEngine can optionally inform a delegate object of significant events during processing of a template, including beginning/ending blocks, or encountering errors.
- Global and template-specific variables. You can define a set of variables which exist for the lifetime of the engine, and also specify variables which only apply to a certain template.
- Access variables using familiar Key-Value Coding (KVC) key-paths, with enhancements. For example, if you had an NSDictionary containing an NSArray for the key “foo”, and that array contained 5 NSDictionaries, each of which had an NSString for the key “bar”, you could access the value of the fifth dictionary’s “bar” object using this syntax:
foo.4.bar(remembering that array indices are zero-based!)
MGTemplateEngine requires Mac OS X 10.5 (Leopard) or later, and can be downloaded from my public Subversion repository at http://svn.cocoasourcecode.com/MGTemplateEngine
You can also read the documentation here:
Get in touch with me via email (details here) if you have feature requests or bug reports, and if you use MGTemplateEngine in your app, be sure to let me know so I can link to you. General praise and thanks can go into the comment box below. ;)
(Finally, and in a small voice, remember the donation link on my Cocoa source code page…)
I plan to continue improving MGTemplateEngine in the future, and I hope you’ll find it useful!
Update: Added the % operator to the if marker. Syntax is if x % y, which as you’d expect returns true if x is not evenly divisible by y, and false otherwise. Very handy within for loops for creating alternating rows, as shown in the (also updated) sample template.
Also added the cycle marker, which takes any number of arguments and will output the next one in the list each time the tag is encountered. Great within loops to cycle between a set of values (e.g. again for alternating row colors). Sample template updated to show this.
10 Comments