thoom/phandlebars

Handlebars.js based templating engine for the Silex framework

Thoom Phandlebars

Summary

Phandlebars allows you to use Handlebars templates in your Silex applications. Rather than reimplementing the Handlebars library in PHP, this provider uses server-side Javascript (primarily with node.js) to both compile the Handlebars templates you've created (making the generated JS file also available for your client-side handling) and process templates on the server., _(*1)

Installation

There are two parts to the installation: the PHP hooks into your Silex application and the required server-side applications., _(*2)

Silex Application

There are these options currently:, _(*3)

1. debug: If debug is true, then the compiled file will be overwritten with each request. If false, it will only build the compiled file if it doesn't exist.
2. library: By default, the compiled JS file will use the Handlebars runtime library. If you need to use the full library instead (for instance, if you dynamically compile on the client side), then pass in HandlebarsServiceProvider::LIBRARY_FULL.
3. minify: If true, the script will attempt to minify the file using the runtime.minify command.
4. path.compiled.client: This is the full file path of where you want the compiled client-only Javascript file to reside. The location should be writable by your web user.
5. path.compiled.server: This is the full file path of where you want the server compiled Javascript file to reside.
6. path.templates.client: The directory where all of the client-only Handlebars templates are stored. Note that all of your templates should end with .handlebars.
7. path.templates.server: The directory where all of the server-only Handlebars templates are stored. Note that all of your templates should end with .handlebars.
8. runtime.minify: If not set, the script will attempt to minify the client file using uglifyjs command.
9. runtime.node: If not set, the script will attempt to run node from using node command.

As an example:, _(*4)

$app->register(new Thoom\Provider\HandlebarsServiceProvider(), array(
    'handlebars.options' => array(
        'debug' => $app['debug'],
        'minify' => true,
        'path.compiled.client' => $app['cache_dir'] . '/js/handlebars-compiled.js',
        'path.compiled.server' => $app['cache_dir'] . '/compiled.js',
        'path.templates.client' => __DIR__ . '/templates/client',
        'path.templates.server' => __DIR__ . '/templates/server',
    )
));

Server

The provider needs a few server cli applications installed in order to render and compile templates., _(*5)

Node.js

Easy to install using the package manager of your choice. For instance, with Ubuntu:, _(*6)

$ apt-get install nodejs build-essential

This assumes that your node executable is installed and accessible from node. If you need to use a different command, change the runtime.node configuration option., _(*7)

Handlebars.js

You'll need to install using NPM., _(*8)

$ apt-get install npm
$ npm install -g handlebars

UglifyJS (optional)

If you want to minify your compiled templates, you'll need to install UglifyJS., _(*9)

$ npm install -g uglify-js

If you prefer another minifier, note that it just needs to accept data from STDIN and outputs to STDOUT. To change the minifier, change the runtime.minify configuration option., _(*10)

To Use

Silex Application

Precompile

You may wish to precompile the script. This can be accomplished by calling the renderer from your application using the following command:, _(*11)

$app['handlebars']->server();

To precompile handlebars for client only scripts:, _(*12)

$app['handlebars']->client();

Server-side rendering

To render a server-side template for "index.handlebars":, _(*13)

$app->get('/', function (Application $app) {
    return $app['handlebars']->render('index');
})->bind('homepage');

To add a global variable (like a user array) to be available to your templates:, _(*14)

$app['handlebars']->addGlobal('user', $userArray);

To pass data to the template at render time, pass in a array as the second argument:, _(*15)

$app['handlebars']->render('index', array('foo' => 'fez'));

To return an Http header other than 200, pass in a 3rd argument:, _(*16)

$app['handlebars']->render('not-found', array('foo' => 'fez'), 404);

Note: Since the Handlebars templates are processed in Javascript using node, you can only pass items that are JSON serializable., _(*17)

Handlebars templates

In addition to the standard Handlebars.js options, you have a few more options that allow you to extend templates similar to Twig., _(*18)

To create a master template ('master.handlebars'), use the {{#block}} tag:, _(*19)

<html>
    <head>
        <title>{{#block "title"}}Master Template{{/block}}</title>
    </head>
    ...

In your child template, you would use the {{#override}} and {{extend}} tags:, _(*20)

{{#override "title"}}Child Template{{/override}}

{{extend "master"}}

This would print:, _(*21)

<html>
    <head>
        <title>Child Template</title>
    </head>
    ...

Notice that unlike Twig templates, the extend tag is found at the bottom of the script. This is required because of how Handlebars parses templates., _(*22)

Additional Tags

path

This convenience expression takes all of your Silex named routes and makes them available in your templates., _(*23)

If your named route "login" has a path of "/login", you'd use:, _(*24)

{{path "login" }}

If your named route "section" has a path of "/section/{section}", you'd use:, _(*25)

{{path "section" section="my-section" }}