TemplateTwigReplace by marcostoll

Use Twig template engine instead of plain-php templates in ProcessWire

ProcessWire Module "Template Twig Replace"

This module offers you template devlopment using the Twig templating engine.

Instead of contaminating your template's and chunk's markup with php code, you would have the Twig templating syntax at hand.

Old school php templating:

<body>
	<?php if ($page->children()->getTotal() > 0): ?>
	<div class="subnavi">
		<ul>
			<?php foreach ($page->children() as $child): ?>
			<li><a href="<?php print $child->url; ?>"><?php print $child->title; ?></a></li>
			<?php endforeach; ?>
		</ul>
	</div>
	<?php endif; ?>

	<h1><?php print $page->title; ?></h1>
</body>

Twig-style templating:

<body>
	{% if page.children().getTotal() > 0 %}
	<div class="subnavi">
		<ul>
			{% for child in page.children() %}
			<li><a href="{{ child.url }}">{{ child.title }}</a></li>
			{% endfor %}
		</ul>
	</div>
	{% endif %}

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

Installing the module


Just copy the module files into you site/modules/ folder or downoload it via the ModuleManager.
Your directory structure should look like this:

site/
|-> modules/
|--|-> TemplateTwigReplace
|--|--|-> Twig-1.15.0/
|--|--|--|-> Twig/
|--|--|-> README.md
|--|--|-> TemplateTwigReplace.module

After deploying the module files go to Setup/Modules in your ProcessWire backend. You should find the Template Twig Replace module in the Template section. Hit install and be ready.

Configuring the module


The Template Twig Replace module offers a small set of configuration options. The module will be installed with ready-to-start default values.

  1. Auto-import fuel
    List the names of the magic ProcessWire fuel variables (page, pages, config, session, input, user).
    See ProcessWire API Variables for further details.
  2. Don't render these templates with twig A list of templates (i.e admin or Formbuilder templates) that shouldn't be rendered with twig.
  3. Enable Twig Cache
    Activate the cache option for storing compiled Twig templates.
    Speeds up your template rendering. Maybe deactivated when in developing mode.
  4. Twig Cache Directory
    Define the name of the directory storing the Twig template cache.
  5. Auto Reload Twig Cache
    Invalid compiled template cache file's if template source file is updated.
  6. Auto Escape Twig variables
    Define a automatic escape strategy for Twig handling template output. Should be turned of in most cases due to ProcessWire handling output escaping before.

Options 2-5 will be passed as environment options to the Twig render engine. Be sure to consult the documentation for further information.

Dependancies


The Template Twig Replace module uses and depends on the Twig libraries. The module will currently be shipped with Twig v1.15.0 which can also be retrieved here.

Future versions of the Template Twig Replace module may use newer versions of Twig but will allways be deployed with all necessary files included.

Module Interaction


Template Twig Replace can be used as stand-alone module, but it seamlessly integrates with theTemplate Data Providers module.

All variables provided by custom PageDataProvider and ChunkDataProvider class will be accessible in yout Twig templates as well.

A template example:

<body>
	{{ page.renderChunk('/includes/subnavi.twig', page) }}

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

	<!-- assuming the PageDataProvider defined $this->page->foo in populate() -->
	<div>{{ page.foo }}</div>

	<!-- assuming the PageDataProvider defined $this->bar in populate() -->
	<div>{{ bar }}</div>
</body>

A chunk example:

<!-- assuming the ChunkDataProvider defined $this->hasChildren in populate() -->
{% if hasChildren %}
<div class="subnavi">
	<ul>
		<!-- assuming the ChunkDataProivder defined $this->parent = $context[0] in setContext() -->
		{% for child in parent.children() %}
		<li><a href="{{ child.url }}">{{ child.title }}</a></li>
		{% endfor %}
	</ul>
</div>
{% endif %}

Using the twig file extension


When using Twig templates it is best to configure ProcessWire to use the twig file extension to get maxmimum support from your ide.

ProcessWire defines the default phpfile extensions for templates in its core config (wire/config.php, option $config->templateExtension). But you don't have to mess with the core files. Just add the follwing line to your site config (site/config.php):

$config->templateExtension = 'twig';

Attention:
Be sure to remane the default admin template from site/templates/admin.php to site/templates/admin.twig! Otherwise your ProcessWire backend won't work if you've change the template extension option.

Accessing the twig environment from outside the module


There are a couple of reasons to access the twig environment from outside the module (e.g. to register custom filters).

To do this the module offers a public method getTwig() that returns the Twig_Environment instance. The module itself is defined as autoloading, so it should be accessible via the modules registry at all times. The Twig autoloader will be registered as well.
Use the following code:

// retrieve the Twig_Environment instance
$twig = wire('modules')->get('TemplateTwigReplace')->getTwig();

// manipulate the twig environment
// example code taken from http://twig.sensiolabs.org/doc/advanced.html#filters
$filter = new Twig_SimpleFilter('rot13', function ($string) {
    return str_rot13($string);
});
$twig->addFIlter($filter);

Honorable mentions


The templates was inspired by the Template Twig module by porl.
Find forum support here.

License


This module is released under the MIT License. See [LICENSE.txt]LICENSE.txt).

Install and use modules at your own risk. Always have a site and database backup before installing new modules.

Twitter updates

  • There’s a new modules directory on the ProcessWire site now up and running. In this post we’ll cover a few details about what’s changed and what’s new—More
    20 November 2020
  • ProcessWire 3.0.168 core updates — More
    26 October 2020
  • This week a 2nd new module for processing Stripe payments has been added to FormBuilder. Unlike our other Stripe Inputfield, this new one supports 3D Secure (SCA) payments. We’ll take a closer look at it in this post, plus a live demo— More
    16 October 2020

Latest news

  • ProcessWire Weekly #342
    In the 342nd issue of ProcessWire Weekly we're going to check out brand new admin theme called Admin Theme Canvas, a new module called MatomoWire, latest ProcessWire core updates, and more. Read on!
    Weekly.pw / 28 November 2020
  • New ProcessWire modules directory
    There’s a new modules directory on the ProcessWire site now up and running. In this post we’ll cover a few details about what’s changed and what’s new.
    Blog / 20 November 2020
  • Subscribe to weekly ProcessWire news

“To Drupal, or to ProcessWire? The million dollar choice. We decided to make an early switch to PW. And in retrospect, ProcessWire was probably the best decision we made. Thanks are due to ProcessWire and the amazing system and set of modules that are in place.” —Unni Krishnan, Founder of PigtailPundits