Creating a theme

Owned by Former user (Deleted)
Apr 15, 2020
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 change 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.
  • Roots: This is currently the best choice for basing a theme off. It is unopinionated and includes Bootstrap 3 CSS framework, along with all Less files for all components.
  • Basis: This is built off Roots with a number of small changes introducing a small aesthetic improvements. It also includes some settings to allow colour changes which may be enough for some instances.

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 customisation are attempted in the following order to reduce maintenance:

  1. Overriding LESS variables - these are unlikely to change and are likely to be used in more and more locations
  2. Overriding CSS
  3. Overriding Mustache Templates
  4. Overriding renderers
  5. Core customisation's - 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