Template Engine Factory

A ProcessWire module integrating template engines such as Twig. It allows to render pages or individual templatesvia template engine and encourages to separate logic from markup by implementing a simple MVC pattern.

• For a quick introduction, please read the Getting Started section of this readme.
• More information is available in the official Documentation.

Version 2.x of this module differs from the 1.x version in many ways. Modules providing template engines must beinstalled with Composer. Twig is currently the only template engine implemented for the 2.x major version. Pleasetake a look at the update guide, as the new version introduces backwardscompatibility breaks. The 1.x version of the module is available on the 1.x branch.

Requirements

• ProcessWire 3.0 or newer
• PHP 7.0 or newer
• Composer

Installation

Execute the following command in the root directory of your ProcessWire installation:

composer require wanze/template-engine-factory:^2.0

This installs the module and its bundled template engine called TemplateEngineProcessWire. This template engine usesProcessWire's internal TemplateFile class for rendering. Other template engines are added to the factory by installingseparate ProcessWire modules.

Installing Twig and other template engines

Each template engine is a separate ProcessWire module. For example, if you want to use Twig,execute the following command:

composer require wanze/template-engine-twig:^2.0

This will install the TemplateEngineTwig and TemplateEngineFactory modules in one step, no need to install bothseparately. It also installs the Twig dependencies for us, pretty neat! ✌️

ℹ️ This module includes test dependencies. If you are installing it on production with composer install, make sure topass the --no-dev flag to omit autoloading any unnecessary test dependencies!.

Configuration

The module offers the following configuration options:

• Template Engine The template engine used to render pages and templates. Any installed engine is listed here.
• Path to templates Relative path from the site directory where template files are stored. E.g. templates/views/ resolves to /site/templates/views/.
• Enable automatic page rendering Check to delegate the rendering of pages to the template engine.You may enable or disable this behaviour for specific templates.
• API variable to interact with the template engine Enter a name for the API variable used to pass data fromthe ProcessWire template (Controller) to the template engine.
• Enabled templates Restrict automatic page rendering to the templates selected here.
• Disabled templates Select templates of pages that should not automatically be rendered via template engine.Do not use in combination with the Enabled templates configuration,either enable or disable templates.

More configuration options might be available in the module providing a template engine, e.g. themodule TemplateEngineTwig offers several configuration related to Twig.

Available Template Engines

• ProcessWire A template engine using ProcessWire's TemplateFile class for rendering. This engine is bundled withthis module, but it is not installed automatically. Install the module TemplateEngineProcessWire and select theengine in the TemplateEngineFactory module configuration.
• Twig See: https://github.com/wanze/TemplateEngineTwig

Getting Started

This section assumes that Twig is used as active template engine, but the usage is excatly the same for any othertemplate engine.

Using the Template Engine to render templates

Assume the following Twig template exists in /site/templates/views/foo.html.twig

<h1>{{ title }}</h1>
{% if body %}
    <p>{{ body }}</p>
{% endif %}

The template can be rendered anywhere with the Template Engine Factory module:

$factory = wire('modules')->get('TemplateEngineFactory');
// Render foo.html.twig with some data.
$factory->render('foo', ['title' => 'Foo', 'body' => 'Hello World']);

Automatic Page Rendering

If enabled, this feature uses the template engine to render ProcessWire pages when calling Page::render.By default, the module tries to find a Twig template matching the same name as the ProcessWire template:

• /site/templates/views/home.html.twig corresponds to /site/templates/home.php
• /site/templates/views/about.html.twig corresponds to /site/templates/about.php

ProcessWire templates have access to a $view API variable which can be used to pass data to the template engine.As the template engine is now responsible to output markup, ProcessWire templates can be seen as Controllers.They process the request and pass data to the View layer via the $view API variable.

Examples

Consider the following ProcessWire template in /site/templates/home.php

// Form has been submitted, do some processing, send mail, save data... 
if ($input->post->form) {
  // ...
  $session->redirect('./');
}
// Forward some data to twig
$view->set('nav_items', $pages->get('/')->children());

The corresponding Twig template in /site/templates/views/home.html.twig might look like this:

<h1>{{ page.title }}</h1>

<ul class="nav">
{% for item in nav_items %}
    <li><a href="{{ item.url }}">{{ item.title }}</a></li>
{% endfor %}
</ul>

<form name="form">
    <input type="text" name="email">
    <input type="submit" value="Submit">
</form>

Note that the ProcessWire template does not echo out any markup. It just contains business logic and uses the $view APIvariable to pass data to the Twig template. That's it! The most simple MVC pattern available in ProcessWire. ????