Add docs on theme.controller setting (simplesamlphp#1026)

tvdijen · web-flow · commit b6de826bba15 · 2018-12-24T08:24:41.000+01:00
* Update simplesamlphp-theming.md

* Add theme.controller config setting
diff --git a/config-templates/config.php b/config-templates/config.php
@@ -792,6 +792,15 @@
      */
     //'theme.header' => 'SimpleSAMLphp'
 
+    /**
+     * A template controller, if any.
+     *
+     * Used to intercept certain parts of the template handling, while keeping away unwanted/unexpected hooks. Set
+     * the 'theme.controller' configuration option to a class that implements the
+     * \SimpleSAML\XHTML\TemplateControllerInterface interface to use it.
+     */
+    //'theme.controller' => '',
+    
     /*
      * Templating options
      *
diff --git a/docs/simplesamlphp-theming.md b/docs/simplesamlphp-theming.md
@@ -99,6 +99,7 @@ You can put resource files within the www folder of your module, to make your mo
 ```
 modules
 └───mymodule
+    └───lib
     └───themes
     └───www
         └───logo.png
@@ -130,6 +131,13 @@ If you need to make more extensive customizations to the base template, you shou
 
 Any references to `$this->data['baseurlpath']` in old-style templates can be replaced with `{{baseurlpath}}` in Twig templates. Likewise, references to `\SimpleSAML\Module::getModuleURL()` can be replaced with `{{baseurlpath}}module.php/mymodule/...`
 
+Even more advanced changes can be made by defining a theme controller in `config.php`:
+
+    'theme.controller' => '\SimpleSAML\Module\mymodule\FancyThemeController',
+
+This requires you to implement `\SimpleSAML\XHTML\TemplateControllerInterface.php` in your module's `lib`-directory.
+The class can then modify the Twig Environment and the variables passed to the theme's templates. In short, this allows you to set additional global variables and to write your own Twig filters and functions.
+
 See the [Twig documentation](https://twig.symfony.com/doc/1.x/templates.html) for more information on using variables and expressions in Twig templates, and the SimpleSAMLphp wiki for [our conventions](https://github.com/simplesamlphp/simplesamlphp/wiki/Twig-conventions).
 
 The wiki also includes some information on [migrating translations](https://github.com/simplesamlphp/simplesamlphp/wiki/Migrating-translation-in-Twig) and [migrating templates](https://github.com/simplesamlphp/simplesamlphp/wiki/Twig:-Migrating-templates).
