xp-forge / mustache
The Mustache template language implemented for the XP Framework
Installs: 32 543
Dependents: 1
Suggesters: 0
Security: 0
Stars: 1
Watchers: 4
Forks: 0
Open Issues: 1
Requires
- php: >=7.0.0
- xp-framework/core: ^12.0 | ^11.0 | ^10.0
- xp-framework/tokenize: ^9.0 | ^8.0
Requires (Dev)
- xp-forge/json: ^5.0 | ^4.0 | ^3.0 | ^2.0
- xp-framework/io-collections: ^10.0 | ^9.0 | ^8.0
- xp-framework/test: ^2.0 | ^1.0
This package is auto-updated.
Last update: 2024-10-24 13:52:38 UTC
README
The mustache template language implemented for the XP Framework.
use com\github\mustache\MustacheEngine; $transformed= (new MustacheEngine())->render( 'Hello {{name}}', ['name' => 'World'] );
Introduction
Read the excellent mustache man-page for a start.
Features supported
This implementation supports all standard features of the current specification:
- Interpolation:
{{var}}
({{&var}}
and triple mustaches for unescaped) and the dot-notation. By default misses will be replaced by empty strings. - Comments:
{{! comment }}
. Comments will appear in the parse tree but of course will be excluded when rendering. - Delimiters:
{{=@ @=}}
will change the starting and ending delimiter to the@
sign. Arbitrary length delimiters are supported. - Sections:
{{#section}}
as well as inverted sections:{{^section}}
are supported. - Partials:
{{> partial}}
will load a template calledpartial.mustache
from the template loader. - Implicit iterators: Written as
{{.}}
, the current loop value will be selected.
The optional lambdas module as well as the parent context extension (../name
) are also supported.
Lambdas
If the value is a closure, it will be invoked and the raw text (no interpolations will have been performed!) will be passed to it:
Template
{{# wrapped }} {{ name }} is awesome. {{/ wrapped }}
Data
[ 'name' => 'Willy', 'wrapped' => function($text) { return '<b>'.$text.'</b>'; } ];
Output
<b>Willy is awesome.</b>
Extended usage
The $text
parameter passed is actually a com.github.mustache.Node
instance but may be treated as text as it overloads the string cast. In order to work with it, the node's evaluate()
method can be called with the com.github.mustache.Context
instance given as the second argument:
[ 'name' => 'Willy', 'wrapped' => function($node, $context) { return '<b>'.strtoupper($node->evaluate($context)).'</b>'; } ]
Template loading
Per default, templates are loaded from the current working directory. This can be changed by passing a template loader instance to the engine:
use com\github\mustache\{MustacheEngine, FilesIn}; use io\Folder; $engine= new MustacheEngine(); $engine->withTemplates(new FilesIn(new Folder('templates'))); $transformed= $engine->transform('hello', ['name' => 'World']);
This will load the template stored in the file templates/hello.mustache
. This template loader will also be used for partials.
Templates can also be loaded from the class loader, use the com.github.mustache.ResourcesIn
and pass it a class loader instance (e.g. ClassLoader::getDefault()
to search in all class paths) for this purpose.
Compiled templates
If you wish to apply variables to a template more than once, you can speed that process up by precompiling templates and using them later on:
use com\github\mustache\MustacheEngine; $engine= new MustacheEngine(); $template= $engine->compile($template); // Later on: $result1= $engine->evaluate($template, $variables1); $result2= $engine->evaluate($template, $variables2);
Helpers
Think of helpers as "omnipresent" context. They are added to the engine instance via withHelper()
and will be available in any rendering context invoked on that instance.
Template
{{# bold }} This is {{ location }}! {{/ bold }}
Call
use com\github\mustache\MustacheEngine; $engine= new MustacheEngine(); $engine->withHelper('bold', function($text) { return '<b>'.$text.'</b>'; }); $transformed= $engine->render($template, ['location' => 'Spartaaaaa']);
Output
<b>This is Spartaaaaa!</b>
Using objects
You can also use instance methods as helpers, e.g.
// Declaration class LocalizationHelpers { public function date($list, $context) { return $context->lookup($list->nodeAt(0)->name())->toString('d.m.Y'); } public function money($list, $context) { // ... } } // Usage with engine instance $engine->withHelper('local', new LocalizationHelpers());
{{#local.date}}{{date}}{{/local.date}}
Spec compliance
Whether this implementation is compliant with the official spec can be tested as follows:
$ curl -sSL https://github.com/mustache/spec/archive/master.zip -o master.zip $ unzip master.zip && rm master.zip $ xp test com.github.mustache.** -a spec-master/specs/