TemplateEngineMustache 2.0.0

README.md

@@ -1,52 +1,68 @@
-TemplateEngineMustache
-====================
-ProcessWire module adding [Mustache](https://mustache.github.io/) templates to the TemplateEngineFactory.
+# TemplateEngineTwig
 
-## Installation
-Install the module just like any other ProcessWire module. Check out the following guide: http://modules.processwire.com/install-uninstall/
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![ProcessWire 3](https://img.shields.io/badge/ProcessWire-3.x-orange.svg)](https://github.com/processwire/processwire)
 
-This module requires TemplateEngineFactory: https://github.com/wanze/TemplateEngineFactory
+A ProcessWire module adding Mustache to the [TemplateEngineFactory](https://github.com/wanze/TemplateEngineFactory).
 
-After installing, don't forget to enable Mustache as engine in the TemplateEngineFactory module's settings.
+## Requirements
 
-## Configuration (over TemplateEngineProcesswire Module Configuration)
-* **Path to templates** Path to folder where you want to store your Smarty template files.
-* **Template files suffix** The suffix of the template files, default is *mustache*.
+* ProcessWire `3.0` or newer
+* TemplateEngineFactory `2.0` or newer
+* PHP `7.0` or newer
+* Composer
 
-## Setting Helpers
+> The `1.x` version of this module is available on the [1.x branch](https://github.com/blue-tomato/TemplateEngineMustache/tree/1.x).
+Use this version if you still use _TemplateEngineFactory_ `1.x`.  
 
-```php
-$view->setHelpers([
-  'myHelperFunction' => function($text) {
-    return trim($text);
-  }
-]);
+## Installation
+
+Execute the following command in the root directory of your ProcessWire installation:
 
 ```
+composer require blue-tomato/template-engine-mustache:^2.0
+```
+
+This will install the _TemplateEngineMustache_ and _TemplateEngineFactory_ modules in one step. Afterwards, don't forget
+to enable Mustache as engine in the _TemplateEngineFactory_ module's configuration.
+
+> ℹ️ This module includes test dependencies. If you are installing on production with `composer install`, make sure to
+pass the `--no-dev` flag to omit autoloading any unnecessary test dependencies!.
 
-## Examples
+## Configuration
 
+The module offers the following configuration:
+
+* **`Template files suffix`** The suffix of the Twig template files, defaults to `mustache`.
+* **`Provide ProcessWire API variables in Mustache templates`** API variables (`$pages`, `$input`, `$config`...)
+are accessible in Twig,
+e.g. `{{ config }}` for the config API variable.
+* **`Debug`** If enabled, Mustache outputs debug information.
+
+## Extending Mustache
+
+It is possible to extend Mustache after it has been initialized by the module. Hook the method `TemplateEngineMustache::initMustache`
+to register custom functions, extensions, global variables, filters etc.
+
+Here is an example how you can use the provided hook to attach a custom function.
 
-First expose data (in this case all story pages) to the mustache view being rendered next.
 ```php
-// In file: /site/templates/stories.php
 
-$stories = $pages->find('template=blogstory');
-$view->set('stories', $stories);
+wire()->addHookAfter('TemplateEngineMustache::initMustache', function (HookEvent $event) {
+    /** @var \Mustache_Engine $mustache */
+    $mustache = $event->arguments('mustache');
+
+    $mustache->setHelpers([
+			'myHelperFunction' => function($text) {
+				return trim($text);
+			}
+		]);
+});
+
+// ... and then use it anywhere in a Mustache template:
+
+{{#myHelperFunction}} {{someVariable}} {{/myHelperFunction}}
 ```
 
-Then use the passed in data (story pages) in your mustache template file.
-```html
-<!-- In file: /site/templates/views/stories.mustache -->
-
-<h1>Stories</h1>
-<ul>
-{{#stories}}
-  <li>
-    <a href="{{url}}">
-      {{title}}
-    </a>
-  </li>
-{{/stories}}
-</ul>
-```
+> The above hook can be put in your `site/init.php` file. If you prefer to use modules, put it into the module's `init()`
+method and make sure that the module is auto loaded.

TemplateEngineMustache.module.php

@@ -0,0 +1,109 @@
+<?php
+
+namespace ProcessWire;
+
+use TemplateEngineMustache\TemplateEngineMustache as MustacheEngine;
+
+/**
+ * Adds Mustache templates to the TemplateEngineFactory module.
+ */
+class TemplateEngineMustache extends WireData implements Module, ConfigurableModule
+{
+    /**
+     * @var array
+     */
+    private static $defaultConfig = [
+        'template_files_suffix' => 'mustache',
+        'api_vars_available' => 1,
+        'debug' => 'config',
+    ];
+
+    public function __construct()
+    {
+        parent::__construct();
+
+        $this->wire('classLoader')->addNamespace('TemplateEngineMustache', __DIR__ . '/src');
+        $this->setDefaultConfig();
+    }
+
+    /**
+     * @return array
+     */
+    public static function getModuleInfo()
+    {
+        return [
+            'title' => 'Template Engine Mustache',
+            'summary' => 'Mustache templates for the TemplateEngineFactory',
+            'version' => 200,
+            'author' => 'Blue Tomato',
+            'href' => 'https://processwire.com/talk/topic/6834-module-Mustache-for-the-templateenginefactory/',
+            'singular' => true,
+            'autoload' => true,
+            'requires' => [
+                'TemplateEngineFactory>=2.0.0',
+                'PHP>=7.0',
+                'ProcessWire>=3.0',
+            ],
+        ];
+    }
+
+    public function init()
+    {
+        /** @var \ProcessWire\TemplateEngineFactory $factory */
+        $factory = $this->wire('modules')->get('TemplateEngineFactory');
+
+        $factory->registerEngine('Mustache', new MustacheEngine($factory->getArray(), $this->getArray()));
+    }
+
+    private function setDefaultConfig()
+    {
+        foreach (self::$defaultConfig as $key => $value) {
+            $this->set($key, $value);
+        }
+    }
+
+    /**
+     * @param array $data
+     *
+     * @throws \ProcessWire\WireException
+     * @throws \ProcessWire\WirePermissionException
+     *
+     * @return \ProcessWire\InputfieldWrapper
+     */
+    public static function getModuleConfigInputfields(array $data)
+    {
+        /** @var Modules $modules */
+        $data = array_merge(self::$defaultConfig, $data);
+        $wrapper = new InputfieldWrapper();
+        $modules = wire('modules');
+
+        /** @var \ProcessWire\InputfieldText $field */
+        $field = $modules->get('InputfieldText');
+        $field->label = __('Template files suffix');
+        $field->name = 'template_files_suffix';
+        $field->value = $data['template_files_suffix'];
+        $field->required = 1;
+        $wrapper->append($field);
+
+        $field = $modules->get('InputfieldCheckbox');
+        $field->label = __('Provide ProcessWire API variables in Mustache templates');
+        $field->description = __('API variables (`$pages`, `$input`, `$config`...) are accessible in Mustache, e.g. `{{ config }}` for the config API variable.');
+        $field->name = 'api_vars_available';
+        $field->checked = (bool) $data['api_vars_available'];
+        $wrapper->append($field);
+
+        /** @var \ProcessWire\InputfieldSelect $field */
+        $field = $modules->get('InputfieldSelect');
+        $field->label = __('Debug');
+        $field->name = 'debug';
+        $field->addOptions([
+            'config' => __('Inherit from ProcessWire'),
+            0 => __('No'),
+            1 => __('Yes'),
+        ]);
+        $field->value = $data['debug'];
+        $wrapper->append($field);
+
+        return $wrapper;
+    }
+}

composer.json

@@ -0,0 +1,33 @@
+{
+    "name": "blue-tomato/template-engine-mustache",
+    "type": "pw-module",
+    "description": "ProcessWire module adding Mustache to the TemplateEngineFactory",
+    "keywords": [ "smarty-engine", "smarty", "processwire"],
+    "homepage": "https://github.com/blue-tomato/TemplateEngineMustache",
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "Blue Tomato",
+            "email": "[email protected]",
+            "homepage": "https://github.com/blue-tomato"
+        },
+        {
+            "name": "TemplateEngineMustache Contributors",
+            "homepage": "https://github.com/blue-tomato/TemplateEngineMustache/contributors"
+        }
+    ],
+    "require": {
+        "php": ">=7.0",
+        "hari/pw-module": "~1.0",
+        "mustache/mustache": "~2.12",
+        "wanze/template-engine-factory": "^2.0"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^6"
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "TemplateEngineSmarty\\Test\\": "tests/src/"
+        }
+    }
+}