Add DOCUMENTATION.md and hopefully fix broken tests in Travis

Author: wanze

DOCUMENTATION.md

@@ -1,15 +1,147 @@
 # Template Engine Factory Documentation
 
+## Table of Contents
+
+1. [Updating from `1.x` to `2.x`](#updating-from-1x-to-2x)
+2. [Controllers](#controllers)
+3. [Hooks](#hooks)
+4. [Best Practices](#best-practices)
+5. [Implementing a Template Engine](#implementing-a-template-engine)
+6. [Running Tests](#running-tests)
+
+
 ## Updating from `1.x` to `2.x`
 
+The `2.x` major version introduces several backwards compatibility breaks. The amount of required manual update steps
+depends on how many features were used. The following list _should_ cover the most important changes: 
+
+* The API variable `$factory` is no longer available. Use `$modules->get('TemplateEngineFactory')` to get an instance of
+the `\ProcessWire\TemplateEngineFactory` class.
+* The factory has a new configuration `templates_path`, indicating where the engine's templates are stored. This config
+was previously defined on template engine level. If you have customized this setting, make sure to update the value in
+the `TemplateEngineFactory` module's config. Defaults to `templates/views`.
+* _Chunks_ are now called _Controllers_. While the semantics remain the same, the public API has changed. Please
+read the [Controllers](#controllers) chapter on how to update your code.
+* The method `TemplateEngineFactory::instance()` (plus some aliases) do no longer exist. Use
+`TemplateEngineFactory::render()` to render a given template of the engine.
+* On template engine level, the confusing `global_template` setting does no longer exist. Use the introduced hook
+`___resolveTemplate` to resolve a custom template when a page gets rendered. The default strategy still looks for a template
+with the same name as the ProcessWire template.
+
+## Controllers
+
+A _controller_ wraps a ProcessWire template executing some logic and a template file of the active engine, rendering the
+output. This is how the _Automatic page rendering_ feature works, by using the template file of a page as controller. By
+defining custom controllers, you get the the same functionality:
+
+```php
+$factory = $modules->get('TemplateEngineFactory');
+
+// Get the sidebar controller, responsible to render a sidebar.
+$controller = $factory->controller('controllers/sidebar.php', 'partials/sidebar.html.twig');
+
+// Optional: You might pass some data to the controller.
+$controller->nPosts = 3;
+
+// Executing the controller renders the associated template via template engine.
+$controller->execute();
+```
+
+The controller and template file from the above example might look like this:
+
+```php
+// site/templates/controllers/sidebar.php
+ 
+$posts = $pages->find("template=blog-post,limit=$nPosts");
+
+// We have access to the $view API variable, connecting us to the template.
+$view->posts = $posts;
+```
+
+```twig
+// site/templates/views/partials/sidebar.twig.html
+
+{% for post in posts %}
+    <h3>{{ post.title }}</h3>
+{% endfor %}
+```
+
+### Updating from `1.x`
+
+* Use the `TemplateEngineFactory::controller` factory method instead of `TemplateEngineFactory::chunk`.
+* Always provide the controller file and the template file.
+* Call `Controller::execute` to process the logic in the controller and to render the template.
+
+```php
+// Version 1.x
+$chunk = $factory->chunk('chunks/nav-item');
+$chunk->render();
+
+// Version 2.x
+$controller = $factory->controller('chunks/nav-item', 'chunks/nav-item');
+$controller->execute();
+```
+
 ## Hooks
 
-### `___shouldRenderPage`
+The TemplateEngineFactory provides several hooks to influence the automatic page rendering process.
+
 ### `___resolveTemplate`
-### `___getTemplateVariables`
 
-## Best Practises
+Use this hook to customize the template being used when rendering a page. By default, the module looks for
+a template with the same name as the page template's name. For example, when rendering the homepage
+with the `home` template, the factory loads the `home.html.twig` twig template.
+
+```php
+wire()->addHookAfter('TemplateEngineFactory::resolveTemplate', function (HookEvent $event) {
+    $event->return = 'customTemplate';
+});
+```  
+
+---
+
+### `___resolveTemplateVariables`
+
+This hook allows to customize the template variables available in your template. Normally,
+the variables are set in the controllers via `$view` API variable. For example, calling 
+`$view->foo = 'bar'` in your controller makes the `foo` variable accessible in the template. If you
+need some _global_ variables available for all pages being rendered, hook them up like this:
+
+```php
+wire()->addHookAfter('TemplateEngineFactory::resolveTemplateVariables', function (HookEvent $event) {
+    $event->return = array_merge(
+        $event->return,
+        [
+            'user' => $this->wire('user'),
+        ]
+    );
+});
+```  
+
+> The above example makes the current user available in all templates. However, changes are high that the
+template engine already has access to all ProcessWire API variables. If you are using Twig, you can toggle this
+behaviour in the _TemplateEngineTwig_ module's configuration.
+
+---
+
+### `___shouldRenderPage`
+
+Use this hook to customize if a page should be rendered by the template engine.
+
+```php
+wire()->addHookAfter('TemplateEngineFactory::shouldRenderPage', function (HookEvent $event) {
+    $page = $event->arguments('page');
+    
+    // Never render pages with the api template.
+    if ($page->template->name === 'api') {
+        $event->return = false;
+    }
+});
+```
+
+## Best Practices
 
 ## Implementing a Template Engine
 
-## Executing Tests
+## Running Tests
+

README.md

@@ -3,15 +3,16 @@
 [![Build Status](https://travis-ci.org/wanze/TemplateEngineFactory.svg?branch=next)](https://travis-ci.org/wanze/TemplateEngineFactory)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-A ProcessWire module integrating template engines such as Twig. It allows to render pages or individual templates
+A ProcessWire module integrating template engines such as _Twig_. It allows to render pages or individual templates
 via template engine and encourages to separate logic from markup by implementing a simple _MVC_ pattern. 
 
 * For a quick introduction, please read the [Getting Started](#getting-started) section of this readme.
 * More information is available in the official [Documentation](DOCUMENTATION.md).
 
 > Version `2.x` of this module differs from the `1.x` version in many ways. Modules providing template engines _must_ be
 installed with Composer. Twig is currently the only template engine implemented for the `2.x` major version. Please
-take a look at the [update guide](), as the new version introduces backwards compatibility breaks.
+take a look at the [update guide](DOCUMENTATION.md#updating-from-1x-to-2x), as the new version introduces backwards
+compatibility breaks.
 
 ## Requirements
 
@@ -41,7 +42,7 @@ composer require wanze/template-engine-twig:^2.0
 ```
 
 This will install the _TemplateEngineTwig_ and _TemplateEngineFactory_ modules in one step, no need to install both
-separately. It also installs the Twig dependencies for us, pretty neat!
+separately. It also installs the Twig dependencies for us, pretty neat! ✌️
 
 > ℹ️ This module includes test dependencies. If you are installing it on production with `composer install`, make sure to
 pass the `--no-dev` flag to omit autoloading any unnecessary test dependencies!.

TemplateEngineProcesswire.module.php

@@ -29,7 +29,7 @@ public static function getModuleInfo()
         ];
     }
 
-    public function ready()
+    public function init()
     {
         /** @var \ProcessWire\TemplateEngineFactory $factory */
         $factory = $this->wire('modules')->get('TemplateEngineFactory');