Merge pull request #1 from justonestep/develop

Adds setMultiple and renderChunk methods

Author: wanze

README.md

@@ -43,6 +43,13 @@ if ($input->post->form) {
 $view->set('foo', 'bar');
 $view->set('show_nav', true);
 $view->set('nav_pages', $pages->get('/')->children());
+
+// Or:
+$view->setMultiple(array(
+  'foo' => 'bar',
+  'show_nav' => true,
+  'nav_pages' => $pages->get('/')->children()
+));
 ```
 In the example above, some logic is processed if a form was sent. Note that there is no markup generated, because this should now be done by the corresponding template file! Over the new API variable `$view`, key/value pairs are passed to the template. Here is an example how the template file could look like:
 ```php
@@ -86,10 +93,70 @@ $chunk = $factory->load('chunks/product_chunk.tpl');
 $chunk->set('product_title', $page->title);
 $chunk->set('date', date('d.m.Y'));
 $chunk_output = $chunk->render();
-$view->set('chunk', $chunk_output);
+$view->set('chunk', $chunk_output); // if you want to set more than a single value, use setMultiple()
 ```
 The example above loads a template file called "product_chunk.tpl" and passes some variables. Calling "render()" returns the rendered markup of the template file.
 
+### Output markup of a chunk
+
+A chunk is a reusable part of a template. That means you can use it multiple times between different template files.
+Furthermore you could put contextual arguments as an array like `array('item' => $item, 'hello' => 'world')` into it.
+
+```php
+// in template file: /site/templates/view/template.tpl
+<?php foreach ($nav_pages as $p): ?>
+  <?php $page->renderChunk('chunks/nav-item', array('page' => $p)); ?>
+<?php endforeach; ?>
+```
+
+Assume there is installed the module "TemplateEngineTwig" and Twig is chosen as the active template engine. The template file could look like this:
+
+```html
+// in template file: /site/templates/view/template.twig
+{% for p in nav_pages %}
+  {% include 'chunks/nav-item', { 'page': p } %}
+{% endfor %}
+```
+
+To render this chunk there must exists two related files. Assuming `chunks/nav-item` this would be:
+
+* /site/templates/chunks/nav-item.php
+* /site/templates/view/chunks/nav-item.tpl
+
+If you pass contextual arguments, you can access them inside the `.php`-file by using `$this->key`.
+As you're used to, you can pass key/value pairs to the template using the new API variable `$view`.
+
+#### Example: How to use a chunk
+
+*In template file: /site/templates/view/template.twig*
+```php
+<?php foreach ($nav_pages as $p): ?>
+  <?php $page->renderChunk('chunks/nav-item', array('page' => $p)); ?>
+<?php endforeach; ?>
+```
+
+*/site/templates/chunks/nav-item.php*
+```php
+<?php namespace ProcessWire;
+
+$foo = 'do some logic // something with the contextual data';
+$author = $this->page->createdUser;
+
+$view->setMultiple( array(
+  'author' => $author,
+  'item' => $this->page,
+  'foo' => $foo
+));
+```
+
+*/site/templates/view/chunks/nav-item.tpl*
+```php
+Author: <?= $author ?> <br />
+<a href="<?= $item->url ?>" title="<?= $foo ?>">
+  <?= $item->title ?>
+</a>
+```
+
 ## Important: Caching
 Since former ProcessWire templates are now controllers that generally do not output any markup, the ProcessWire template cache should *NOT* be active. Deactivate cache in the settings of your template under the section "Cache".
 
@@ -125,6 +192,11 @@ class TemplateEngineMyEngine extends TemplateEngine implements Module, Configura
   {
     // Pass a key/value pair to your engine
   }
+
+  public function setMultiple($pairs = array())
+  {
+    // Pass multiple key/value pairs to your engine
+  }
 
   public function render()
   {

TemplateEngine.php

@@ -83,6 +83,18 @@ public function __set($key, $value)
         $this->set($key, $value);
     }
 
+    /**
+     * @param array $pairs
+     */
+    public function __setMultiple($pairs = array())
+    {
+      if (is_array($pairs)) {
+        foreach ($pairs as $key => $value) {
+          $this->template->set($key, $value);
+        }
+      }
+    }
+
 
     /**
      * Set a key/value pair to the template engine
@@ -93,6 +105,14 @@ public function __set($key, $value)
     abstract public function set($key, $value);
 
 
+    /**
+     * Set multiple key/value pairs to the template engine
+     *
+     * @param array $pairs
+     */
+    abstract public function setMultiple($pairs = array());
+
+
     /**
      * Render markup from template engine
      *
@@ -233,4 +253,4 @@ protected function initConfig()
             self::$loaded_config[$this->className] = array_merge($this->getDefaultConfig(), $configs);
         }
     }
-}
+}

TemplateEngineCache.php

@@ -75,13 +75,50 @@ class TemplateEngineFactory extends WireData implements Module, ConfigurableModu
         }
         $this->wire($this->get('api_var'), $engine);
         $this->addHookAfter('Page::render', $this, 'hookRender');
+        $this->addHook('Page::renderChunk', $this, 'renderChunk');
         // If the engine supports caching, attach hooks to clear the cache when saving/deleting pages
         if (in_array('TemplateEngineCache', class_implements($engine))) {
             $this->pages->addHookAfter('save', $this, 'hookClearCache');
             $this->pages->addHookAfter('delete', $this, 'hookClearCache');
         }
     }
 
+    /**
+     * Hook callback for Page::renderChunk
+     *
+     * This method is added as a hook to each \Page instance.
+     * The first argument passed must be the path to the chunk file render
+     * (relative to wire('config')->paths->templates)
+     *
+     * You may pass an array of additional arguments as a second argument
+     * which will be passed as contextual data to the chunk
+     *
+     * @param HookEvent $event
+     */
+    public function renderChunk(HookEvent $event) {
+        $chunkFile = $event->arguments(0);
+        // remove file extension if exists
+        $pathInfo = pathinfo($chunkFile);
+        if (array_key_exists('extension', $pathInfo)) {
+          $chunkFile = $pathInfo['dirname'] . '/' . pathinfo($chunkFile, PATHINFO_FILENAME);
+        }
+
+        $context = array_slice($event->arguments(), 1, null, false);
+        $engine = $this->getInstanceById($this->get('engine'), $chunkFile, true);
+        if (is_null($engine)) return; // template file is missing
+
+        $chunkBaseFile = $this->config->paths->templates . $chunkFile . '.' . $this->config->templateExtension;
+        if (!file_exists($chunkBaseFile)) return;
+        $tplFile = new \ProcessWire\TemplateFile($chunkBaseFile);
+        if (is_array($event->arguments(1))) {
+          foreach ($event->arguments(1) as $key => $value) $tplFile->$key = $value;
+        }
+        echo $tplFile->render();
+
+        $view = $this->wire('view', $engine);
+        echo $view->render();
+    }
+
 
     /**
      * Method executed after Page::render()
@@ -206,8 +243,9 @@ class TemplateEngineFactory extends WireData implements Module, ConfigurableModu
         }
         $engine->initEngine();
         if ($as_api_var) {
-            $this->wire($this->get('api_var'), $engine);
+          $this->wire($this->get('api_var'), $engine);
         }
+
         return $engine;
     }
 

TemplateEngineFactory.module

@@ -30,6 +30,14 @@ public function initEngine() {}
     public function set($key, $value) {}
 
 
+    /**
+     * Set multiple key/value pairs to the template
+     *
+     * @param array $pairs
+     */
+    public function setMultiple($pairs = array()) {}
+
+
     /**
      * Render markup from template file
      *
@@ -40,4 +48,4 @@ public function render()
         return '';
     }
 
-}
+}

TemplateEngineNull.php

@@ -12,10 +12,10 @@ require_once('TemplateEngine.php');
 class TemplateEngineProcesswire extends TemplateEngine implements Module, ConfigurableModule
 {
 
-    /**
-     * @var TemplateFile
-     */
-    protected $template;
+   /**
+    * @var \TemplateFile $template
+    */
+   protected static $template;
 
 
     /**
@@ -60,6 +60,21 @@ class TemplateEngineProcesswire extends TemplateEngine implements Module, Config
     }
 
 
+    /**
+     * Set multiple key/value pairs to the template
+     *
+     * @param array $pairs
+     */
+    public function setMultiple($pairs = array())
+    {
+      if (is_array($pairs)) {
+        foreach ($pairs as $key => $value) {
+          $this->template->set($key, $value);
+        }
+      }
+    }
+
+
     /**
      * Render markup from template file
      *
@@ -109,4 +124,4 @@ class TemplateEngineProcesswire extends TemplateEngine implements Module, Config
         return $wrapper;
     }
 
-}
+}