https://github.com/xp-forge/handlebars-templates
Handlebars templates for XP web frontends
https://github.com/xp-forge/handlebars-templates
assets handlebars-helpers handlebars-partials handlebars-templates php7 php8 yaml-frontmatter
Last synced: about 2 months ago
JSON representation
Handlebars templates for XP web frontends
- Host: GitHub
- URL: https://github.com/xp-forge/handlebars-templates
- Owner: xp-forge
- Created: 2021-02-13T10:52:08.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-04-12T09:17:33.000Z (about 1 year ago)
- Last Synced: 2025-03-12T23:02:12.476Z (3 months ago)
- Topics: assets, handlebars-helpers, handlebars-partials, handlebars-templates, php7, php8, yaml-frontmatter
- Language: PHP
- Homepage:
- Size: 102 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: ChangeLog.md
Awesome Lists containing this project
README
Handlebars for XP web frontends
===============================
[](https://github.com/xp-forge/handlebars-templates/actions)
[](https://github.com/xp-framework/core)
[](https://github.com/xp-framework/core/blob/master/LICENCE.md)
[](http://php.net/)
[](http://php.net/)
[](https://packagist.org/packages/xp-forge/handlebars-templates)
Handlebars template engine implementation to be used in conjunction with [XP web frontends](https://github.com/xp-forge/frontend).
Example
-------
Wiring happens inside your web application:
```php
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'))
)
];
}
}
```
Templates
---------
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:
```handlebars
---
nav:
/: Home
/about: About
/login: Login
---
...
{{#each nav}}
{{.}}
{{/each}}
```
Fragments
---------
Instead of rendering an entire template, we can render special inline partials we call *fragments*. They are declared as follows:
```handlebars
...
{{#*fragment "listing"}}
- {{.}}
{{#each items}}
{{/each}}
{{/fragment}}
```
...and are rendered by selecting them via *fragment()* in our handler:
```php
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 `
- ...
Helpers
-------
On top of the [built-in functionality in Handlebars](https://github.com/xp-forge/handlebars), this library includes the following essential helpers:
* `encode`: Performs URL-encoding
* `equals`: Tests arguments for equality
* `contains`: Tests whether a string or array contains a certain value
* `size`: Returns string length or array size
* `min`: Returns smallest element
* `max`: Returns largest element
* `any`: Test whether any of the given arguments is truthy
* `none`: Test whether none of the given arguments is truthy
* `all`: Test whether all of the given arguments is truthy
### Date handling
```php
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:
```handlebars
{{date "2021-02-13"}}
{{date "13.02.2021 17:56:00"}}
{{date 1613209181}}
{{date 1613209181279 timestamp="ms"}}
{{date created}}
{{date created format="d.m.Y"}}
{{date created format="us:short"}}
{{date created timezone="America/New_York"}}
```
### Logging
The `log` helper will echo the arguments passed to it:
```handlebars
{{log user}}
{{log "User profile:" user}}
```
When using the development webserver, this shows the debug page:
In production environments, logs will end up on the server's standard output:
Standalone
----------
To use the template engine by itself, simply instantiate and call its *render()* method:
```php
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.