README

The ViewServiceProvider gives engine-agnostic templating capabilities to your Speedwork application.

Installation with Composer

curl -s http://getcomposer.org/installer | php
php composer.phar require speedwork/view

Usage

Just register the service provider and optionally pass in some defaults.

$app->register(new Speedwork\View\ViewServiceProvider(), array(
    'view.globals' => array('foo' => 'bar'),
    'view.default_engine' => 'mustache'
));

The provider registers the ArrayToViewListener which intercepts the output from your controllers and wraps it with a View object. For it to work, you have to return an array of data from your controller function.

Views

Normally you do not need to instantiate any view entities on your own; the listener will convert your controller output. If you wish to do it manually, the syntax is as follows:

$view = $app['engine']->create($template = '/path/to/template', $context = array('foo' => 'bar'));

Views can be rendered by calling the render() function, or casting to string:

$output = $view->render();
$output = (string) $view;

Again, you should not need to render your views manually since they will be handled by the Response object.

View Context

The view entity is simply an instance of ArrayObject, so you can use regular array notation to set the context, along with convenience functions like with():

$view['foo'] = 'bar';
$view->with(array('foo' => 'bar'));

To insert into the global context, use share():

$view->share(array('foo' => 'bar'));

You can initialize the global context by overriding view.globals.

Engines

This library does not handle any actual view rendering; that task is delegated to the templating library of your choice. Currently adapters are provided for:

• Mustache
• Smarty
• Twig
• Aura.View
• Plates
• Raw PHP
• Token replacement using strtr()

There is a special DelegatingEngine which acts as a registry for multiple different engines, selecting the appropriate one based on the template file extension. Since Aura.View, Plates and Raw PHP all use the same default file extension (.php), you will need to manually configure the extension mapping as follows:

$app->register(new Speedwork\View\ViewServiceProvider(), array(
    'view.default_engine' => 'php',
    'view.engines' => array(
        'php' => 'view.engine.plates'
    )
));

Composite Views

Views can be nested inside another:

$view->nest($app['engine']->create('foobar.html'), 'section');

For a single view, it is equivalent to:

$view['section'] = $app['engine']->create('foobar.html');

However, the difference lies in nesting multiple views in the same location. Doing this will place the child views adjacent to each other rather than overwriting:

$view->nest($app['engine']->create('foobar.html'), 'section');
$view->nest($app['engine']->create('foobar.html'), 'section'); // foobar.html is now repeated twice

What's more, you can mix and match different engines:

$mustacheView = $app['engine']->create('foo.mustache');
$smartyView = $app['engine']->create('bar.tpl')->nest($mustacheView, 'section');

Nested views will inherit the context of their parent views.

Exception Handling

All rendering exceptions are captured and stored in a shared ExceptionBag.

To access the last thrown exception, or return all of them:

$exception = $app['engine']->getExceptionBag()->pop();
$exceptions = $app['engine']->getExceptionBag()->all();

License

Released under the MIT license. See the LICENSE file for details.

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Make your changes
4. Run the tests, adding new ones for your own code if necessary (phpunit)
5. Commit your changes (git commit -am 'Added some feature')
6. Push to the branch (git push origin my-new-feature)
7. Create new Pull Request