Merge branch 'dev'

Author: dmolsen

README.md

@@ -1,13 +1,83 @@
 # Mustache PatternEngine for Pattern Lab PHP
 
-The Mustache PatternEngine allows you to use [Mustache](https://mustache.github.io) as the template language for Pattern Lab PHP.  Once the PatternEngine is installed you can use Mustache-based StarterKits and StyleguideKits.
+The Mustache PatternEngine allows you to use [Mustache](https://mustache.github.io) as the template language for Pattern Lab PHP. Once the PatternEngine is installed you can use Mustache-based StarterKits and StyleguideKits.
 
 ## Installation
 
-Pattern Lab PHP uses [Composer](https://getcomposer.org/) to manage project dependencies. To install the Mustache PatternEngine:
+The Mustache PatternEngine will come pre-installed with the **Pattern Lab Standard Edition**.
+
+### Composer
+
+Pattern Lab PHP uses [Composer](https://getcomposer.org/) to manage project dependencies with Pattern Lab Editions. To add the Mustache PatternEngine to the dependencies list for your Edition you can type the following in the command line at the base of your project:
 
     composer require pattern-lab/patternengine-mustache
 
+See Packagist for [information on the latest release](https://packagist.org/packages/pattern-lab/patternengine-mustache).
+
+## Overview
+
+This document is broken into two parts:
+
+* [Extending Mustache](#extending-mustache)
+* [Available Loaders for Plugin Developers](#available-loaders)
+
+## Extending Mustache
+
+Mustache comes with two ways to extend the underlying template parser:
+
+* [Filters](https://github.com/bobthecow/mustache.php/wiki/FILTERS-pragma)
+* Lambdas
+
+The Mustache PatternEngine enables these features via Helpers.
+
+### Helpers
+
+The requirements for using helpers with Pattern Lab:
+
+* Files must go in `source/_mustache-components/helpers`
+* Files must have the extension `.helper.php` (_this can be modified in the config_)
+* The helper **must** set the variable `$helper`
+* Only one helper per file (_e.g. can only set `$helper` once per file_)
+
+An example function called `verbatim.helper.twig` in `source/_mustache-components/helpers`:
+
+```php
+<?php
+
+$helper = function ($text) {
+	return "{{=%%pl pl%%=}}".$text."%%pl={{ }}=pl%%";
+};
+
+?>
+```
+
+This helper would be used like this in a pattern. Note that the tag is using the filename and that this is an example of a lambda:
+
+```mustache
+{{# verbatim }}
+	{{ this won't be parsed }}
+{{/ verbatim }}
+```
+
+Mustache also allows dot notation with helpers. An example function called `case.helper.twig` in `source/_mustache-components/helpers`:
+
+```php
+<?php
+
+$helper = array(
+    'lower' => function($value) { return strtolower((string) $value); },
+    'upper' => function($value) { return strtoupper((string) $value); },
+));
+
+?>
+```
+
+This helper would be used like this in a pattern. Note that the tag is using the filename and that this is an example of a filter:
+
+```mustache
+{{ greeting | case.upper }}
+```
+
 ## Available Loaders
 
 If you're building a plugin that will be parsing Mustache files you have access to three loaders. It's recommended that you use these instead of accessing Mustache directly as these loaders will work with other PatternEngines.

composer.json

@@ -30,13 +30,12 @@
 	},
 	"extra": {
 		"patternlab": {
-			"config": [
-				{
-					"lineageMatch": "{{>([ ]+)?([A-Za-z0-9-_]+)(?:\\:[A-Za-z0-9-]+)?(?:(| )\\(.*)?([ ]+)?}}",
-					"lineageMatchKey": 2,
-					"patternExtension": "mustache"
-				 }
-			]
+			"config": {
+				"lineageMatch": "{{>([ ]+)?([A-Za-z0-9-_]+)(?:\\:[A-Za-z0-9-]+)?(?:(| )\\(.*)?([ ]+)?}}",
+				"lineageMatchKey": 2,
+				"patternExtension": "mustache",
+				"mustacheHelperExt": "helper.php"
+			}
 		}
 	}
 }

src/PatternLab/PatternEngine/Mustache/Helper.php

@@ -13,32 +13,35 @@
 namespace PatternLab\PatternEngine\Mustache\Loaders;
 
 use \PatternLab\PatternEngine\Loader;
+use \PatternLab\PatternEngine\Mustache\MustacheUtil;
 
 class FilesystemLoader extends Loader {
-	
+
 	/**
 	* Load a new Mustache instance that uses the File System Loader
 	*/
 	public function __construct($options = array()) {
-		
+
 		$mustacheOptions                    = array();
 		$mustacheOptions["loader"]          = new \Mustache_Loader_FilesystemLoader($options["templatePath"]);
 		$mustacheOptions["partials_loader"] = new \Mustache_Loader_FilesystemLoader($options["partialsPath"]);
-		
+		$mustacheOptions["helpers"]         = MustacheUtil::loadHelpers();
+		$mustacheOptions["pragmas"]         = array(\Mustache_Engine::PRAGMA_FILTERS);
+
 		$this->instance = new \Mustache_Engine($mustacheOptions);
-		
+
 	}
-	
+
 	/**
 	* Render a template
 	* @param  {Array}        the options to be rendered by Mustache
 	*
 	* @return {String}       the rendered result
 	*/
 	public function render($options = array()) {
-		
+
 		return $this->instance->render($options["template"], $options["data"]);
-		
+
 	}
-	
+
 }

src/PatternLab/PatternEngine/Mustache/Loaders/FilesystemLoader.php

@@ -16,40 +16,39 @@
 use \PatternLab\Dispatcher;
 use \PatternLab\PatternEngine\Mustache\Loaders\Mustache\PatternStringLoader as Mustache_Loader_PatternStringLoader;
 use \PatternLab\PatternEngine\Mustache\Loaders\Mustache\PatternPartialLoader as Mustache_Loader_PatternPartialLoader;
-use \PatternLab\PatternEngine\Mustache\Helper;
+use \PatternLab\PatternEngine\Mustache\MustacheUtil;
 use \PatternLab\PatternEngine\Loader;
 
 class PatternLoader extends Loader {
-	
+
 	/**
 	* Load a new Mustache instance that uses the Pattern Loadere
 	*/
 	public function __construct($options = array()) {
-		
-		Dispatcher::getInstance()->dispatch("mustacheRule.gatherHelpers");
-		
+
 		//default var
 		$patternSourceDir = Config::getOption("patternSourceDir");
-		
+
 		$mustacheOptions                    = array();
 		$mustacheOptions["loader"]          = new Mustache_Loader_PatternStringLoader();
 		$mustacheOptions["partials_loader"] = new Mustache_Loader_PatternPartialLoader($patternSourceDir,array("patternPaths" => $options["patternPaths"]));
-		$mustacheOptions["helpers"]         = Helper::get();
-		
+		$mustacheOptions["helpers"]         = MustacheUtil::loadHelpers();
+		$mustacheOptions["pragmas"]         = array(\Mustache_Engine::PRAGMA_FILTERS);
+
 		$this->instance = new \Mustache_Engine($mustacheOptions);
-		
+
 	}
-	
+
 	/**
 	* Render a pattern
 	* @param  {Array}        the options to be rendered by Mustache
 	*
 	* @return {String}       the rendered result
 	*/
 	public function render($options = array()) {
-		
+
 		return $this->instance->render($options["pattern"], $options["data"]);
-		
+
 	}
-	
+
 }

src/PatternLab/PatternEngine/Mustache/Loaders/PatternLoader.php

@@ -13,28 +13,33 @@
 namespace PatternLab\PatternEngine\Mustache\Loaders;
 
 use \PatternLab\PatternEngine\Loader;
+use \PatternLab\PatternEngine\Mustache\MustacheUtil;
 
 class StringLoader extends Loader {
-	
+
 	/**
 	* Load a new Mustache instance that is just a vanilla Mustache rendering engine for strings
 	*/
 	public function __construct($options = array()) {
-		
-		$this->instance = new \Mustache_Engine;
-		
+
+		$mustacheOptions                    = array();
+		$mustacheOptions["helpers"]         = MustacheUtil::loadHelpers();
+		$mustacheOptions["pragmas"]         = array(\Mustache_Engine::PRAGMA_FILTERS);
+
+		$this->instance = new \Mustache_Engine($mustacheOptions);
+
 	}
-	
+
 	/**
 	* Render a string
 	* @param  {Array}        the options to be rendered by Mustache
 	*
 	* @return {String}       the rendered result
 	*/
 	public function render($options = array()) {
-		
+
 		return $this->instance->render($options["string"], $options["data"]);
-		
+
 	}
-	
+
 }

src/PatternLab/PatternEngine/Mustache/Loaders/StringLoader.php

@@ -0,0 +1,71 @@
+<?php
+
+/*!
+ * Mustache Util Class
+ *
+ * Copyright (c) 2015 Dave Olsen, http://dmolsen.com
+ * Licensed under the MIT license
+ *
+ * Various utility methods for the Mustache PatternEngine
+ *
+ */
+
+namespace PatternLab\PatternEngine\Mustache;
+
+use \PatternLab\Config;
+use \PatternLab\Console;
+use \Symfony\Component\Finder\Finder;
+
+class MustacheUtil {
+	
+	/**
+	* Load helpers for the Mustache PatternEngine
+	*
+	* @return {Array}         an array of helpers
+	*/
+	public static function loadHelpers() {
+		
+		// set-up helper container
+		$helpers = array();
+		
+		// load defaults
+		$helperDir = Config::getOption("sourceDir").DIRECTORY_SEPARATOR."_mustache-components/helpers";
+		$helperExt = Config::getOption("mustacheHelperExt");
+		$helperExt = $helperExt ? $helperExt : "helper.php";
+		
+		if (is_dir($helperDir)) {
+			
+			// loop through the filter dir...
+			$finder = new Finder();
+			$finder->files()->name("*\.".$helperExt)->in($helperDir);
+			$finder->sortByName();
+			foreach ($finder as $file) {
+				
+				// see if the file should be ignored or not
+				$baseName = $file->getBasename();
+				if ($baseName[0] != "_") {
+					
+					include($file->getPathname());
+					
+					// $key may or may not be defined in the included file
+					// $helper needs to be defined in the included file
+					if (isset($helper)) {
+						if (!isset($key)) {
+							$key = $file->getBasename(".".$helperExt);
+						}
+						$helpers[$key] = $helper;
+						unset($helper);
+						unset($key);
+					}
+					
+				}
+				
+			}
+			
+		}
+		
+		return $helpers;
+		
+	}
+	
+}