From b6de826bba157b16f1587607f69d4c8c5a6d35ba Mon Sep 17 00:00:00 2001
From: Tim van Dijen <tvdijen@gmail.com>
Date: Mon, 24 Dec 2018 08:24:41 +0100
Subject: [PATCH] Add docs on theme.controller setting (#1026)

* Update simplesamlphp-theming.md

* Add theme.controller config setting
---
 config-templates/config.php   | 9 +++++++++
 docs/simplesamlphp-theming.md | 8 ++++++++
 2 files changed, 17 insertions(+)

diff --git a/config-templates/config.php b/config-templates/config.php
index ddbe91f14..aa1cede4b 100644
--- a/config-templates/config.php
+++ b/config-templates/config.php
@@ -792,6 +792,15 @@ $config = [
      */
     //'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
index 51cbe65b5..a6eb0b623 100644
--- 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).
-- 
GitLab