PHP Template Engine Abstraction Layer
Provides a layer for rendering view templates and defining template plugins and manipulators.



Template Engine Component

TemplateEngine component provides a layer for rendering view templates.

Install the component

The best way to install the component is using Composer.

composer require webiny/template-engine

For additional versions of the package, visit the Packagist page.

Installation error

If you get an error like this:

[RuntimeException]
Package could not be downloaded, sh: 1: svn: not found

Then probably you don't have Subversion installed which is preventing the installation of Smarty library. This can be easily solved by installing the Subversion, prior to the composer install.

$ sudo apt-get install subversion

Usage

The definition of the view template depends on the selected driver. By default the template engine comes with a driver for Smarty, but you can easily add support for Twig or some other template engines.

The provided functionality of every driver is defined by the TemplateEngineInterface which defines the following methods:

  • fetch - fetch the template from the given location, parse it and return the output
  • render - fetch the template from the given location, parse it and output the result to the browser
  • assign - assign a variable and its value into the template engine
  • setTemplateDir - directory where the template files are stored
  • registerPlugin - register a plugin for the template engine

To create a new driver just create a new class that implements the \Webiny\Component\TemplateEngine\Bridge\TemplateEngineInterface and adapt your config.

The default configuration looks like this:

    TemplateEngine:
        Engines:
            Smarty:
                ForceCompile: false
                CacheDir: '/var/tmp/smarty/cache'
                CompileDir: '/var/tmp/smarty/compile'
                TemplateDir: '/var/www/theme/templates'
                AutoEscapeOutput: false
                MuteExpectedErrors: true

Usage

The preferred usage is over the TemplateEngineTrait. Here is an example:

class MyClass
{
    use \Webiny\Component\TemplateEngine\TemplateEngineTrait;

    function __construct() {
        // assing name and id to the template and render it
        $this->templateEngine('Smarty')->render('template.tpl', ['name'=>'John', 'id'=>15]);
    }
}

Smarty

If you wish to use the Smarty template engine, with the built in driver, make sure you include path/to/Smarty/libs/Smarty.class.php somewhere inside you application, before using the component. This is due to the problem that Smarty doesn't provide a suitable autoloader to be integrated with the component.

Plugins & extensions

The template engine is designed so that it can be expanded with different plugins and modifiers, depending on the assigned driver.

Best practice for expanding the template engine is first to create an extension and then register it as a service tagged with the $driverName.Extension, for example Smarty.Extension.

An Extension is a package of one or multiple plugins. Plugin type depends on the template engine, for example, Smarty supports these plugin types:

To create a smarty extension, create a class that extends \Webiny\Component\TemplateEngine\Drivers\Smarty\AbstractSmartyExtension and then overwrite the methods, based on the plugin type your wish to create.

For example, let's say we want to register a modifier called 'customUpper'. First we create our extension class like this:

namespace MyApp\Demo;

class MySmartyExtension extends \Webiny\Component\TemplateEngine\Drivers\Smarty\SmartyExtension
{
    /**
     * @overwrite
     * @return array
     */
    function getModifiers(){
        return [
            new SmartySimplePlugin('custom_upper', 'modifier', [$this, 'customUpper'])
        ];
    }

    /**
     * Callback for my custom_upper modifier.
     *
     * @param $params
     *
     * @return string
     */
    function customUpper($params){
        return strtoupper($params);
    }

    /**
     * Returns the name of the plugin.
     *
     * @return string
     */
    function getName() {
        return 'my_extension';
    }
}

Once we have our extension, we must register it using the service manager:

MyApp:
    CustomExtension:
        Class: \MyApp\Demo\MySmartyExtension
        Tags: [Smarty.Extension]

And that's it, we can now use the modifier in our templates:

{'this is my name'|custom_upper}
// outputs: THIS IS MY NAME

Resources

To run unit tests, you need to use the following command:

$ cd path/to/Webiny/Component/TemplateEngine/
$ composer.phar install
$ phpunit

To learn what you can do with Webiny Framework, checkout Webiny Platform - open-source content management system.

Explore Webiny Framework components:

  • Amazon currently supports implementation of Amazon S3
  • Annotations component for parsing annotations from a class, method or a property
  • Cache provides several caching libraries like Apc, Couchbase, Memcache and Redis
  • ClassLoader a PSR-0, PSR-4 and PEAR class loader
  • Config a very handy library for parsing YAML, INI, JSON and PHP configuration files
  • Crypt library for encoding, decoding and validating hashes
  • Entity an ODM layer (currently only supports MongoDB)
  • EventManager want to do event-based development, this is a library for you
  • Http library for parsing HTTP requests and creating HTTP responses
  • Image library for image manipulation
  • Logger PSR-3 log components for logging code execution in runtime
  • Mailer component for sending emails
  • Mongo MongoDB class wrapper
  • OAuth2 library for working with OAuth2, currently supports Facebook, LinkedIn and Google+
  • REST fully featured REST library with caching, security and rate control
  • Router handles defining, parsing, creating and matching url routes
  • Security provides authorization and authentication layer
  • ServiceManager want to write truly service based, loosely-coupled code, this library provides that
  • StdLib this component provides object wrappers for Arrays, Strings, Urls and DateTime data types
  • Storage storage abstraction layer that simplifies the way you work with files and directories
  • TemplateEngine provides a layer for rendering view templates and defining template plugins and manipulators
  • TwitterOAuth library for working with Twitter API using Twitter OAuth

SIGN UP FOR EARLY BETA ACCESS:

Lastest from our blog:

The Power of the Community

In the focus of recent feedback that I got, I think there is a need for me to justify some of the decisions we made while developing Webiny Framework.

Share & subscribe: