Creating a theme

Owned by Former user (Deleted)
Last updated: Nov 22, 2024 by Dave Wallace
3 min read

Location

All themes need to be placed in the theme directory and named with a unique name (when compared to all components) and need the following files:

  • theme/<themename>/lang/en/theme_<themename>.php -  this contains the language strings used by this theme and needs the strings for 'pluginname' and 'choosereadme'.

  • theme/<themename>/config.php - this contains the configuration for the Theme (see below for more details).

  • theme/<themename>/version.php - this contains the version information for the Theme. As with all plugins, it will need to contain $plugin→version (the version of this component, $plugin→requires (the version of Totara that this Theme requires, and $plugin→component (a machine readable string in the format theme_<name>.

Choosing a base theme

One of the major decisions when creating a theme for Totara is to pick a base theme. In core Learn there are currently three options for a parent theme:

  • Base: This is almost a completely clean canvas containing only font icon CSS (no module CSS) and a very basic layout. It is also injected if it is not included in the Theme inheritance chain, as otherwise font icons will not work. If you do not wish to build a theme using the bootstrap 3 CSS framework, it is the best choice, but requires the most work.

  • Legacy: This is the best choice for basing a Theme off in Totara 13-18. It is unopinionated and includes Bootstrap 3 CSS framework, along with all SCSS files for all components.

  • Ventura: This is built off Legacy with a small number of colour tweaks. It also includes some settings to allow colour changes which may be enough for some instances.

  • Inspire: New in Totara 19, this is the best choice to base a modern Theme off. Like Ventura, it is built off Legacy, but includes a number of UI improvements such as a new primary navigation.

It is also possible to set the parent Theme to a non core Theme.

Changing how functionality is displayed

Depending on the level of customisation required, we recommend that customisations are attempted in the following order to reduce maintenance:

  1. Overriding CSS Variables (aka Custom Properties) - this is our preferred approach for many CSS values that may need to be changed while creating child Themes.

  2. Overriding SCSS variables

  3. Overriding CSS

  4. Overriding Mustache Templates

  5. Overriding PHP renderers

  6. Core customisations - we recommend that you do not do these as there are likely to be changes as we advance Totara 

When doing an upgrade (especially between major versions) ensure that you read upgrade.txt for area's that are themed as there may be changes in core renderers and templates.

Over time, we will be aiming to increase the usage of mustache templates and reducing HTML that is rendered in a non-overwritable way (although these will mainly occur in major versions / Evergreen) in an effort to reduce the number of core customisations made.

For more general changes, there is also the ability to customise:

config.php

This file tells Totara how to interpret the way the theme is to be used. This file will need to contain the following information (or may inherit it from the parent Theme):

  • $THEME→doctype. The HTML doctype to use (usually 'html5')

  • $THEME→name. The Theme's name. This should simply be whatever your theme's name is, most likely whatever you named your theme directory

  • $THEME→sheets. An array containing the names of the CSS stylesheets to include for this theme. Note that right to left stylesheets are automatically detected if they have the -rtl suffix e.g. (styles-rtl.css)

  • $THEME→layouts. An array containing potential page layouts. See Page layouts for more information

  • $THEME→parents. An array containing this themes ancestors with the most recent first (e.g. if you are extending roots, this will be "$THEME→parents =  array('roots', 'base');")

  • $THEME→enable_dock. In Roots and Basis docks have the functionality to be docked to a sidebar. This setting enables or disable this functionality

  • $THEME→yuicssmodules. This is an old setting that defines a list of YUI css files to load. These files interfere with existing styles and it is recommended to set this to an empty string to prevent any files being included

  • $THEME→rendererfactory. Almost all themes need this setting to be set to 'theme_overridden_renderer_factory' or the theme will not be able to customise any core renderers

A full list of available settings can be found in lib/outputlib.php

version.php

This is the same as the version.php under any other component. It should contain the following information:

  • $plugin→version. The version of the theme (usually in the format yyyymmddxx)

  • $plugin→requires. The totara version required (in the format yyyymmddxx)

  • $plugin→component. The machine readable name of the theme (in the format 'theme_<name>')

  • $plugin→dependencies. Any dependencies that this Theme requires - this is an array of key/value pairs with the key being the component (e.g. 'theme_roots') and value being the version of the component