-
Thijs Kinkhorst authoredThijs Kinkhorst authored
Theming the user interface in SimpleSAMLphp
In SimpleSAMLphp every part that needs to interact with the user by using a web page, uses templates to present the XHTML. SimpleSAMLphp comes with a default set of templates that presents a anonymous look.
You may create your own theme, where you add one or more template files that will override the default ones. This document explains how to achieve that.
How themes work
If you want to customize the UI, the right way to do that is to create a new theme. A theme is a set of templates that can be configured to override the default templates.
Configuring which theme to use
In config.php
there is a configuration option that controls theming. You need to set that option and enable the module that contains the theme. Here is an example:
'module.enable' => [
...
'fancymodule' => true,
],
'theme.use' => 'fancymodule:fancytheme',
The theme.use
parameter points to which theme that will be used. If some functionality in SimpleSAMLphp needs to present UI in example with the logout.twig
template, it will first look for logout.twig
in the theme.use
theme, and if not found it will all fallback to look for the base templates.
All required templates SHOULD be available as a base in the templates
folder, and you SHOULD never change the base templates. To customize UI, add a new theme within a module that overrides the base templates, instead of modifying it.
Override only specific templates
The SimpleSAMLphp templates are derived from a base template and include other templates as building blocks. You only need to override the templates or building blocks needed for your change.
SimpleSAMLphp allows themes to override the included templates files only, if needed. That means you can create a new theme fancytheme
that includes only a header and footer template. These templates may refer to your own CSS files, which means that a simple way of making a new look on SimpleSAMLphp is to create a new theme, and copy the existing header, but point to your own CSS instead of the default CSS.
Creating your first theme
The first thing you need to do is having a SimpleSAMLphp module to place your theme in. If you do not have a module already, create a new one:
cd modules
mkdir mymodule
Enable the module by setting `$config['module.enable' => ['mymodule' => true]]`
Then within this module, you can create a new theme named fancytheme
.
cd modules/mymodule
mkdir -p themes/fancytheme/default/
Now, configure SimpleSAMLphp to use your new theme in config.php
:
'theme.use' => 'mymodule:fancytheme',
Next, we copy the header file from the base theme:
cp templates/_header.twig modules/mymodule/themes/fancytheme/default/
In the modules/mymodule/themes/fancytheme/default/includes/_header.twig
file type in something and go to the SimpleSAMLphp front page to see that your new theme is in use.
Adding resource files
You can put resource files within the www/assets
folder of your module, to make your module completely independent with included css, icons etc.
modules
└───mymodule
└───lib
└───themes
└───www
└───assets
└───logo.png
└───style.css
Reference these resources in your custom templates under themes/fancytheme
by using a generator for the URL.
Example for a custom CSS stylesheet file:
{% block preload %}
<link rel="stylesheet" href="{{ asset('style.css', 'mymodule') }}">
{% endblock %}
Migrating to Twig templates
In version 1.15, a new templating system based on Twig 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/...
or the asset()
function like shown above.
Within templates each module is defined as a separate namespace matching the module name. This allows one template to reference templates from other modules using Twig's @namespace_name/template_path
notation. For instance, a template in mymodule
can include the widget template from the yourmodule
module using the notation @yourmodule/widget.twig
. A special namespace, __parent__
, exists to allow theme developers to more easily extend a module's stock template.
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 for more information on using variables and expressions in Twig templates, and the SimpleSAMLphp wiki for our conventions.
The wiki also includes some information on migrating translations and migrating templates.