Merge branch 'dev'

Author: dmolsen

README.md

@@ -8,6 +8,18 @@ Pattern Lab PHP uses [Composer](https://getcomposer.org/) to manage project depe
 
     composer require pattern-lab/patternengine-twig
 
+## Using Twig Macros
+
+The Twig PatternEngine will automatically find and load Twig macros making them available to every pattern. To use this feature add your `.macro` files to `source/_macros/`. If your macro file is called `forms.macro` and it has a macro called `input()` you'd access it in your Twig templates as `{{ forms.input() }}`. **Please note:** ensure that there is no overlap between the keys for your macros and the keys for your data attributes.
+
+## Enabling `dump()`
+
+To use `dump()` set `twigDebug` in `configs/config.yml` to `true`.
+
+## Modifying the Default Date and Interval Format
+
+You can modify the default date and interval formats for Twig by editing the `twigDefaultDateFormat` and `twigDefaultIntervalFormat` in `configs/config.yml`. Set them to an empty string to use Twig's default formats. **Please note:** both must be set for this feature to work.
+
 ## Available Loaders
 
 If you're building a plugin that will be parsing Twig files you have access to three loaders. It's recommended that you use these instead of accessing Twig directly as these loaders will work with other PatternEngines.
@@ -41,9 +53,9 @@ The pattern loader looks for patterns and allows the use of the Pattern Lab-spec
 
 ```php
 $data                  = array(...);
-$patternPath           = "path/to/pattern";
+$patternContent        = file_get_contents("path/to/pattern");
 $patternEngineBasePath = \PatternLab\PatternEngine::getInstance()->getBasePath();
 $patternLoaderClass    = $patternEngineBasePath."\Loaders\PatternLoader";
 $patternLoader         = new $patternLoaderClass($options);
-$code                  = $patternLoader->render(array("pattern" => $patternPath, "data" => $data));
+$code                  = $patternLoader->render(array("pattern" => $patternContent, "data" => $data));
 print $output; // outputs the given pattern

composer.json

@@ -1,6 +1,6 @@
 {
 	"name":             "pattern-lab/patternengine-twig",
-	"description":      "Twig-based Pattern Engine for the PHP version of Pattern Lab",
+	"description":      "Twig-based PatternEngine for Pattern Lab.",
 	"keywords":         ["twig", "pattern lab", "pattern engine"],
 	"homepage":         "http://patternlab.io",
 	"license":          "MIT",
@@ -25,12 +25,18 @@
 	},
 	"require": {
 		"php":            ">=5.3.6",
-		"twig/twig":      "v1.15.1"
+		"twig/twig":      "~1.15"
 	},
 	"extra": {
 		"patternlab": {
 			"config": [
-				{ "patternExtension": "twig" }
+				{ 
+					"patternExtension": "twig",
+					"twigDebug": false,
+					"twigDefaultDateFormat": "",
+					"twigDefaultIntervalFormat": "",
+					"twigMacroExt": "macro"
+				}
 			]
 		}
 	}

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

@@ -12,7 +12,9 @@
 
 namespace PatternLab\PatternEngine\Twig\Loaders;
 
+use \PatternLab\Config;
 use \PatternLab\PatternEngine\Loader;
+use \PatternLab\PatternEngine\Twig\TwigUtil;
 
 class FilesystemLoader extends Loader {
 
@@ -21,8 +23,16 @@ class FilesystemLoader extends Loader {
 	*/
 	public function __construct($options = array()) {
 
-		$twigLoader     = new \Twig_Loader_Filesystem(array($options["templatePath"],$options["partialsPath"]));
-		$this->instance = new \Twig_Environment($twigLoader);
+		// set-up the loader
+		$twigDebug      = Config::getOption("twigDebug");
+		$macroPath      = Config::getOption("sourceDir").DIRECTORY_SEPARATOR."_macros";
+		$twigLoader     = new \Twig_Loader_Filesystem(array($options["templatePath"],$options["partialsPath"],$macroPath));
+		$this->instance = new \Twig_Environment($twigLoader, array("debug" => $twigDebug));
+		
+		// customize the loader
+		$this->instance = TwigUtil::loadDateFormats($this->instance);
+		$this->instance = TwigUtil::loadDebug($this->instance);
+		$this->instance = TwigUtil::loadMacros($this->instance, "filesystem");
 
 	}
 
@@ -34,7 +44,7 @@ public function __construct($options = array()) {
 	*/
 	public function render($options = array()) {
 
-		return $this->instance->render($options["template"].".twig", $options["data"]);
+		return $this->instance->render($options["template"].".".Config::getOption("patternExtension"), $options["data"]);
 
 	}
 

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

@@ -1,20 +1,23 @@
 <?php
 
 /*!
- * Mustache Pattern Engine Loader Class - Patterns
+ * Twig Pattern Engine Loader Class - Patterns
  *
  * Copyright (c) 2014 Dave Olsen, http://dmolsen.com
  * Licensed under the MIT license
  *
- * Sets an instance of Mustache to deal with rendering of patterns
+ * Sets an instance of Twig to deal with patterns. Tries to find
+ * files on system first. If not tries to load them as strings.
  *
  */
 
 namespace PatternLab\PatternEngine\Twig\Loaders;
 
 use \PatternLab\Config;
-use \PatternLab\PatternEngine\Twig\Loaders\Twig\PatternLoader as Twig_Loader_PatternLoader;
+use \PatternLab\PatternEngine\Twig\Loaders\Twig\PatternPartialLoader as Twig_Loader_PatternPartialLoader;
+use \PatternLab\PatternEngine\Twig\Loaders\Twig\PatternStringLoader as Twig_Loader_PatternStringLoader;
 use \PatternLab\PatternEngine\Loader;
+use \PatternLab\PatternEngine\Twig\TwigUtil;
 
 class PatternLoader extends Loader {
 
@@ -23,10 +26,20 @@ class PatternLoader extends Loader {
 	*/
 	public function __construct($options = array()) {
 
-		//default var
-		$patternSourceDir = Config::getOption("patternSourceDir");
-		$twigLoader       = new Twig_Loader_PatternLoader($patternSourceDir,array("patternPaths" => $options["patternPaths"]));
-		$this->instance   = new \Twig_Environment($twigLoader);
+		// set-up the loader
+		$twigDebug            = Config::getOption("twigDebug");
+		$patternSourceDir     = Config::getOption("patternSourceDir");
+		$macroPath            = Config::getOption("sourceDir").DIRECTORY_SEPARATOR."_macros";
+		$patternPartialLoader = new Twig_Loader_PatternPartialLoader($patternSourceDir,array("patternPaths" => $options["patternPaths"]));
+		$patternStringLoader  = new \Twig_Loader_String();
+		$macroLoader          = new \Twig_Loader_Filesystem(array($macroPath));
+		$twigLoader           = new \Twig_Loader_Chain(array($patternPartialLoader, $macroLoader, $patternStringLoader));
+		$this->instance       = new \Twig_Environment($twigLoader, array("debug" => $twigDebug));
+		
+		// customize the loader
+		$this->instance       = TwigUtil::loadDateFormats($this->instance);
+		$this->instance       = TwigUtil::loadDebug($this->instance);
+		$this->instance       = TwigUtil::loadMacros($this->instance, "pattern");
 
 	}
 

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

@@ -12,7 +12,9 @@
 
 namespace PatternLab\PatternEngine\Twig\Loaders;
 
+use \PatternLab\Config;
 use \PatternLab\PatternEngine\Loader;
+use \PatternLab\PatternEngine\Twig\TwigUtil;
 
 class StringLoader extends Loader {
 
@@ -21,8 +23,18 @@ class StringLoader extends Loader {
 	*/
 	public function __construct($options = array()) {
 
-		$twigLoader     = new \Twig_Loader_String();
-		$this->instance = new \Twig_Environment($twigLoader);
+		// set-up the loader
+		$twigDebug      = Config::getOption("twigDebug");
+		$macroPath      = Config::getOption("sourceDir").DIRECTORY_SEPARATOR."_macros";
+		$macroLoader    = new \Twig_Loader_Filesystem(array($macroPath));
+		$stringLoader   = new \Twig_Loader_String();
+		$twigLoader     = new \Twig_Loader_Chain(array($macroLoader, $stringLoader));
+		$this->instance = new \Twig_Environment($twigLoader, array("debug" => $twigDebug));
+		
+		// customize the loader
+		$this->instance = TwigUtil::loadDateFormats($this->instance);
+		$this->instance = TwigUtil::loadDebug($this->instance);
+		$this->instance = TwigUtil::loadMacros($this->instance, "string");
 
 	}
 

src/PatternLab/PatternEngine/Twig/Loaders/Twig/PatternLoader.php renamed to src/PatternLab/PatternEngine/Twig/Loaders/Twig/PatternPartialLoader.php

@@ -15,7 +15,7 @@
 
 use \PatternLab\PatternEngine\Util;
 
-class PatternLoader implements \Twig_LoaderInterface, \Twig_ExistsLoaderInterface {
+class PatternPartialLoader implements \Twig_LoaderInterface, \Twig_ExistsLoaderInterface {
 
 	/** Identifier of the main namespace. */
 	const MAIN_NAMESPACE = '__main__';

src/PatternLab/PatternEngine/Twig/TwigUtil.php

@@ -0,0 +1,92 @@
+<?php
+
+/*!
+ * Twig Pattern Engine Loader Class - String
+ *
+ * Copyright (c) 2014 Dave Olsen, http://dmolsen.com
+ * Licensed under the MIT license
+ *
+ * Sets an instance of Twig to deal with rendering of strings
+ *
+ */
+
+namespace PatternLab\PatternEngine\Twig;
+
+use \PatternLab\Config;
+use \PatternLab\Console;
+use \Symfony\Component\Finder\Finder;
+
+class TwigUtil {
+	
+	/**
+	* Load custom date formats for Twig
+	* @param  {Instance}       an instance of the twig engine
+	*
+	* @return {Instance}       an instance of the twig engine
+	*/
+	public static function loadDateFormats($instance) {
+		
+		$dateFormat     = Config::getOption("twigDefaultDateFormat");
+		$intervalFormat = Config::getOption("twigDefaultIntervalFormat");
+		
+		if ($dateFormat && $intervalFormat && !empty($dateFormat) && !empty($intervalFormat)) {
+			$instance->getExtension("core")->setDateFormat($dateFormat, $intervalFormat);
+		}
+		
+		return $instance;
+		
+	}
+	
+	/**
+	* Enable the debug options for Twig
+	* @param  {Instance}       an instance of the twig engine
+	*
+	* @return {Instance}       an instance of the twig engine
+	*/
+	public static function loadDebug($instance) {
+		
+		if (Config::getOption("twigDebug")) {
+			$instance->addExtension(new \Twig_Extension_Debug());
+		}
+		
+		return $instance;
+		
+	}
+	
+	/**
+	* Load macros for the Twig PatternEngine
+	* @param  {Instance}       an instance of the twig engine
+	* @param  {String}         description of the loader type for the error
+	*
+	* @return {Instance}       an instance of the twig engine
+	*/
+	public static function loadMacros($instance, $instanceType) {
+		
+		// load defaults
+		$macroDir = Config::getOption("sourceDir").DIRECTORY_SEPARATOR."_macros";
+		$macroExt = Config::getOption("twigMacroExt");
+		$macroExt = $macroExt ? $macroExt : "macro";
+		
+		if (is_dir($macroDir)) {
+			
+			// loop through some macro containing dir and run...
+			$finder = new Finder();
+			$finder->files()->name("*.".$macroExt)->in($macroDir);
+			$finder->sortByName();
+			foreach ($finder as $file) {
+				$instance->addGlobal($file->getBasename(".".$macroExt), $instance->loadTemplate($file->getBasename()));
+			}
+			
+		} else {
+			
+			// write warning because the macro dir doesn't exist
+			$macroDirHR = Console::getHumanReadablePath($macroDir);
+			Console::writeWarning("the path <path>".$macroDirHR."</path> doesn't exist so macros won't be loaded for the ".$instanceType." loader...");
+			
+		}
+		
+		return $instance;
+		
+	}
+	
+}