README

A ProcessWire module integrating template engines such as Twig. It allows to render pages or individual templates via 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 be installed with Composer. Please take a look at the update guide, as the new version introduces backwards compatibility 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 uses ProcessWire's internal TemplateFile class for rendering. Other template engines are added to the factory by installing separate 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 module and all Twig dependencies.

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

Configuration

The TemplateEngineFactory 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 from the 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. the module 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 with this module, but it is not installed automatically. Install the module TemplateEngineProcessWire and select the engine in the TemplateEngineFactory module configuration.
Twig See: https://github.com/wanze/TemplateEngineTwig
Pug See: https://github.com/dreerr/TemplateEnginePug
Smarty See: https://github.com/blue-tomato/TemplateEngineSmarty
Mustache See: https://github.com/blue-tomato/TemplateEngineMustache
Latte See: https://github.com/daun/TemplateEngineLatte

Getting Started

This section assumes that Twig is used as active template engine, but the usage is exactly the same for any other chosen template 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 API variable to pass data to the Twig template. That's it! The most simple MVC pattern available in ProcessWire. 😎

wanze / template-engine-factory

Maintainers

Details