Handlebars template engine implementation to be used in conjunction with XP web frontends.
Wiring happens inside your web application:
use web\frontend\{Frontend, AssetsFrom, HandlersIn, Handlebars};
use web\Application;
class App extends Application {
/** Returns routing for this web application */
public function routes() {
return [
'/static' => new AssetsFrom($this->environment->path('src/main/webapp')),
'/' => new Frontend(
new HandlersIn('com.example.app.web'),
new Handlebars($this->environment->path('src/main/handlebars'))
)
];
}
}The templates live in src/main/handlebars, their names corresponding to lowercased version of the handlers' names (Home::class => home.handlebars).
Templates support YAML front matter, which can be used to set defaults for template globals. Example:
Instead of rendering an entire template, we can render special inline partials we call fragments. They are declared as follows:
...and are rendered by selecting them via fragment() in our handler:
use web\frontend\{Handler, Get};
#[Handler]
class Index {
private $list= ['One', 'Two', 'Three'];
#[Get]
public function index() {
return View::named('index')->with(['list' => $this->list]);
}
#[Get('/listing')]
public function partial() {
return View::named('index')->fragment('listing')->with(['list' => $this->list]);
}
}Accessing the URI /listing will render only the <ul>...</ul> instead of the entire document. These fragments can be used in conjunction with frameworks like htmx, see this gist for an example.
On top of the built-in functionality in Handlebars, this library includes the following essential helpers:
encode: Performs URL-encodingequals: Tests arguments for equalitycontains: Tests whether a string or array contains a certain valuesize: Returns string length or array sizemin: Returns smallest elementmax: Returns largest elementany: Test whether any of the given arguments is truthynone: Test whether none of the given arguments is truthyall: Test whether all of the given arguments is truthy
use util\TimeZone;
use web\frontend\Handlebars;
use web\frontend\helpers\Dates;
new Handlebars($templates, [new Dates()]);
// Pass timezone or NULL to use local timezone
new Handlebars($templates, [new Dates(new TimeZone('Europe/Berlin'))]);
new Handlebars($templates, [new Dates(null)]);
// Pass default and named date format
new Handlebars($templates, [new Dates(null, [null => 'd.m.Y'])]);
new Handlebars($templates, [new Dates(null, ['us:short' => 'Y-m-d'])]);The date helper accepts anything the util.Date class accepts as constructor argument, or a util.Date instance itself. To format the date, the format argument can be used with anything the util.Date::toString() method accepts. Here are some examples:
The log helper will echo the arguments passed to it:
When using the development webserver, this shows the debug page:
In production environments, logs will end up on the server's standard output:
To use the template engine by itself, simply instantiate and call its render() method:
use web\frontend\Handlebars;
$engine= new Handlebars('.');
echo $engine->render('home', []);This will render the home.handlebars file and return the result as a string.