diff --git a/docs/simplesamlphp-theming.md b/docs/simplesamlphp-theming.md index 0c66fbde91ea3f948e96767901fa788113294a3d..cfac38020da6159402671cd306798b6f35a76011 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 19523af595a2397051f980bc29990f2fdcecba0d..a4ffd2483d3c320b80ac1e00607b8c154b033cda 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