added error handling to renderChunk and documentation

Author: Tabea David

README.md

@@ -32,6 +32,7 @@ For each controller that is outputting markup, a corresponding template file sho
 Depending on the setting "Global template file" of the activated engine, the factory tries to load the template file of the current page's controller or the global template file. If a template file is found, an instance of it is accessible over the API variable. If no template file is found, the factory assumes that the controller does not output markup over the template engine. In this case, the hook to modify the behaviour of Page::render() is not attached - everything works "normal".
 
 The following example uses the ProcessWire template engine:
+
 ```php
 // In controller file: /site/templates/home.php
 
@@ -43,8 +44,16 @@ 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
 // In template file: /site/templates/view/home.php
 
@@ -60,6 +69,7 @@ In the example above, some logic is processed if a form was sent. Note that ther
 <?php endif; ?>
 ```
 Assume there is installed the module "TemplateEngineSmarty" and Smarty is chosen as the active template engine. The template file could look like this:
+
 ```php
 // In template file: /site/templates/smarty/home.tpl
 
@@ -78,6 +88,7 @@ The introduced API variable acts as a gateway to the active template engine. Thi
 
 ### Load and output markup of other template files
 Use the "TemplateEngineFactory" module to load any template file and output it's markup:
+
 ```php
 // In controller file: /site/templates/product.php
 
@@ -86,10 +97,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 +196,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()
   {

TemplateEngineFactory.module

@@ -86,22 +86,30 @@ class TemplateEngineFactory extends WireData implements Module, ConfigurableModu
     /**
      * Hook callback for Page::renderChunk
      *
-     * This method as added as a hook to each \Page instance.
+     * 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).
+     * (relative to wire('config')->paths->templates)
      *
-     * You may pass an arbitrary amount of additional arguments which will
-     * be passed as contextual data to the chunk data provider.
+     * 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
-     * @see \nw\DataProviders\ChunkDataProvider
      */
     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, true);
+        if (is_null($engine)) return; // template file is missing
 
-        $tplFile = new \ProcessWire\TemplateFile($this->config->paths->templates . $chunkFile . '.' . $this->config->templateExtension);
+        $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;
         }