Basics
To use your own style sheets you will need a TAO extension. This article explains how to create one - or if you have one for other reasons, you can use that one too.
Download the toolkit and place the scss
code in the view
directory of your extension. Your file structure should now look like this:
views/scss/themes
_common
- code shared by item- and platform themesitems
- everything for item themes_common
code shared by all item themesinc
include filesinteractions
interaction specific code
theme-template
boilerplate code
platform
- everything for platform themes_common
code shared by all platform themesinc
include files
theme-template
boilerplate code
In the install/php
section of your extension manifest register the SetItemThemes
and/or the SetPlatformTheme
classes, depending on which part of the styles you wish to modify.
\oat\__myExtensionId__\scripts\install\SetItemThemes::class,
\oat\__myExtensionId__\scripts\install\SetPlatformTheme::class,
Copy the two class templates from the directory code
to /__myExtensionId__/install
and configure them. If TAO is already installed you will need to increase the version of manifest.php
and register the new styles in /scripts/update/Updater.php
. Provided you don't unregister or rename any theme the code for the updater is as follows:
if ($this->isVersion('x.x.x')) {
// platform theme
$setPlatformTheme = new SetPlatformTheme();
$setPlatformTheme([]);
// item themes
$setItemTheme = new SetItemThemes();
$setItemTheme([]);
$this->setVersion('x.y.x');
}
Advanced setup
This part concerns items only. The ItemThemeInstaller
class comes with a number of functions to handle item themes.
Item themes are usually stored in /__myExtensionId__/views/css/themes/items/name-of-the-theme
. For the usage of this class it's assumed that you are using this very setup. For all other setups please use oat\tao\model\ThemeRegistry
directly.
Let's say you start with a regular setup and tao as the default theme. You want to remove tao and install two of your own themes. The registry should eventually look about like this:
'available' => [
[
'id' => 'taoFooDefault',
'name' => 'TAO',
'path' => '/taoFoo/views/css/themes/items/default/theme.css'
],
[
'id' => 'taoFooOther',
'name' => 'The other one',
'path' => '/taoFoo/views/css/themes/items/other/theme.css'
]
],
'default' => 'taoFooOther' // note the prefix
The code for installs and updates is - apart from the themes - identical. All theme ids will be prefixed with your extension id to avoid collisions. If you add the extension prefix yourself it won't be doubled. The tao theme is never prefixed.
$themes = [
'default' => 'The default theme', // equivalent to 'taoFooDefault' => 'The default theme'
'other' => 'The other one'
];
$itemThemeInstaller = new ItemThemeInstaller('taoFoo'); // 'taoFoo' is the id of your extension
$itemThemeInstaller->add($themes);
Now you need to set a default theme, again there will be no prefix duplication
$itemThemeInstaller->setDefault('default');
Eventually you may want to remove the tao theme. Note that ItemThemeInstaller::remove()
also accepts an array of ids as argument.
$itemThemeInstaller->remove('tao');
// with array
$itemThemeInstaller->remove(['tao', 'foo', 'bar']);
What, if the label - the name under which the theme appears in the preview or during delivery - needs to be changed?
$themes = [
'default' => 'The new label'
];
$itemThemeInstaller->update($themes);
Finally you can also restore the defaults. This affects the current item extension only, themes from other extensions stay registered. tao however will be re-installed and set as default.
$itemThemeInstaller->reset();
During development you often have situations where you want to run the installer or updater multiple times. You can do this for all methods without risking errors.
Finalize setup
If this is an update rather than a new installation run php tao/scripts/taoUpdate.php
to register your themes.