From e253d54ae4e245515aafc58bbaad5fabafcb96af Mon Sep 17 00:00:00 2001
From: Guy Halse <guy@tenet.ac.za>
Date: Wed, 28 Feb 2018 11:48:33 +0200
Subject: [PATCH] Document the new Twig templating system
Add some basic documentation on how the new Twig templating system works.
---
docs/simplesamlphp-theming.md | 17 +++++++++++++++++
docs/simplesamlphp-upgrade-notes-1.15.md | 4 +++-
2 files changed, 20 insertions(+), 1 deletion(-)
diff --git a/docs/simplesamlphp-theming.md b/docs/simplesamlphp-theming.md
index 0c66fbde9..cfac38020 100644
--- a/docs/simplesamlphp-theming.md
+++ b/docs/simplesamlphp-theming.md
@@ -114,3 +114,20 @@ Example for a custom CSS stylesheet file:
```html
<link rel="stylesheet" type="text/css" href="<?php echo SimpleSAML_Module::getModuleURL('mymodule/style.css'); ?>" />
```
+
+Migrating to Twig templates
+---------------------------
+
+In version 1.15, a new templating system based on [Twig](https://twig.symfony.com/) was introduced. As modules migrate, it will become necessary for themes to include both the old templating style described above and new Twig-based templates.
+
+Twig works by extending a base template, which can itself include other partial templates. Some of the content of the old `includes/header.php` template is now located in a separate `_header.twig` file. This can be customized by copying it from the base template:
+
+ cp templates/_header.twig modules/mymodule/themes/fancytheme/default/
+
+If you need to make more extensive customizations to the base template, you should copy it from the base theme:
+
+ cp templates/base.twig modules/mymodule/themes/fancytheme/default/
+
+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/...`
+
+See the [Twig documentation](https://twig.symfony.com/doc/1.x/templates.html) for more information on using variables and expressions in Twig templates.
diff --git a/docs/simplesamlphp-upgrade-notes-1.15.md b/docs/simplesamlphp-upgrade-notes-1.15.md
index 19523af59..a4ffd2483 100644
--- a/docs/simplesamlphp-upgrade-notes-1.15.md
+++ b/docs/simplesamlphp-upgrade-notes-1.15.md
@@ -5,7 +5,9 @@ The minimum required PHP version is now 5.4. The dependency on mcrypt has been
dropped.
A new templating system based on Twig has been introduced. The old templating
-system is still available but should be considered deprecated.
+system is still available but should be considered deprecated. Custom themes
+may need to be updated to include Twig-style templates as well. See the
+[theming documentation](simplesamlphp-theming).
A new internationalization system based on Gettext has been introduced. While
old templates can use either the old or the new system (refer to the
--
GitLab