All code examples are here

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 themes
  • items - everything for item themes
    • _common code shared by all item themes
      • inc include files
        • interactions interaction specific code
    • theme-template boilerplate code
  • platform - everything for platform themes
    • _common code shared by all platform themes
      • inc 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.