Documented TwigRenderer 1.1.0 features

Author: weierophinney

doc/book/template/twig.md

@@ -48,3 +48,81 @@ $twig->loadExtension(new CustomExtension();
 // Inject:
 $renderer = new TwigRenderer($twig);
 ```
+
+## Included extensions and functions
+
+The included Twig extension adds support for url generation. The extension is
+automatically activated if the [UrlHelper](../helpers/url-helper.md) and
+[ServerUrlHelper](../helpers/server-url-helper.md) are registered with the
+container.
+
+The following template functions are exposed:
+
+- ``path``: Render the relative path for a given route and parameters. If there
+  is no route, it returns the current path.
+
+  ```twig
+  {{ path('article_show', {'id': '3'}) }}
+  Generates: /article/3
+  ```
+
+- ``url``: Render the absolute url for a given route and parameters. If there is
+  no route, it returns the current url.
+
+  ```twig
+  {{ url('article_show', {'slug': 'article.slug'}) }}
+  Generates: http://example.com/article/article.slug
+  ```
+
+- ``absolute_url``: Render the absolute url from a given path. If the path is
+  empty, it returns the current url.
+
+  ```twig
+  {{ absolute_url('path/to/something') }}
+  Generates: http://example.com/path/to/something
+  ```
+
+- ``asset`` Render an (optionally versioned) asset url.
+
+  ```twig
+  {{ asset('path/to/asset/name.ext', version=3) }}
+  Generates: path/to/asset/name.ext?v=3
+  ```
+
+  To get the absolute url for an asset:
+
+  ```twig
+  {{ absolute_url(asset('path/to/asset/name.ext', version=3)) }}
+  Generates: http://example.com/path/to/asset/name.ext?v=3
+  ```
+
+## Configuration
+
+The following details configuration specific to Twig, as consumed by the
+`TwigRendererFactory`:
+
+```php
+return [
+    'templates' => [
+        'extension' => 'file extension used by templates; defaults to html.twig',
+        'paths' => [
+            // namespace / path pairs
+            //
+            // Numeric namespaces imply the default/main namespace. Paths may be
+            // strings or arrays of string paths to associate with the namespace.
+        ],
+    ],
+    'twig' => [
+        'cache_dir' => 'path to cached templates',
+        'assets_url' => 'base URL for assets',
+        'assets_version' => 'base version for assets',
+        'extensions' => [
+            // extension service names or instances
+        ],
+        'globals' => [
+            // Global variables passed to twig templates
+            'ga_tracking' => 'UA-XXXXX-X'
+        ],
+    ],
+];
+```