Moodle App Remote Themes

Important:

This content of this page has been updated and migrated to the new Moodle Developer Resources. The information contained on the page should no longer be seen up-to-date.

Why not view this page on the new site and help us to migrate more content to the new site!

How do Remote Themes work?

When you enter a site, it downloads any file configured on the mobilecssurl administration field and injects the styles in the app. Every time you change between sites, each style will be enabled or disabled appropriately.

The styles will remain enabled in the login page, but any other page that is not related with a specific site will use the default styles. For example, pages to add or remove sites cannot be customised with Remote Themes.

How can you create your own theme?

First of all, Remote Themes are only available for sites that purchased a Premium subscription for the Moodle App. You can check the different plans in the Apps Portal. If you want, you can follow the instructions in this document without purchasing a subscription and it will work in your development environment.

In order to create your own theme, we recommend that you use the app from master.apps.moodledemo.net and check the styles using the browser inspector. You can use any Chromium-based browser, but you should launch it with some special arguments. You can read more about that in the Using the Moodle App in a browser page. If you need to test a different version of the app, you can also use integration.apps.moodledemo.net for the latest development version or the Docker images for anything more specific.

Once you have everything ready, you can configure your theme by going to "Site administration > Mobile app > Mobile appearance" in your site and setting the mobilecssurl field to a url pointing to a CSS file. This file can be placed inside your Moodle installation in your custom theme, inside a local plugin, or hosted elsewhere.

You can get started with the following example, and you should see the background of the top bar change to red once you log into the app:

body {
    --core-header-toolbar-background: red;
}

Applying theme changes during development

For performance reasons, the app caches the styles after you log in for the first time. So if you make any changes, you won't see them unless you log out and log in again. However, there is a faster way to update them. You can also open the Preferences page in the app and click on the "Synchronise now" button. This will download the files again, and you can use this method to iterate on your styles while you make the theme.

The file can also be cached by the browser, so when you do this make sure to disable network cache as well.

Knowing what to style

Depending on how much you want to customise the UI, you'll need to do different things.

The application defines some CSS variables that can help you customise basic styles, like the one we used in our example above to change the background color of the header toolbar. You can find these variables in the source code, the main ones are defined within theme.light.scss and theme.dark.scss, and you can find others within component styles.

If you need anything more specific, the application is built using the Ionic Framework, so reading their documentation can help you understand how the UI works and which components are available. We have some custom components that you won't find listed on their documentation, but most of them built on top of Ionic's.

Finally, if you need to style something even more specific, you can always browse the source code to see how a specific page is built. You can also use the Elements Panel of your browser to inspect styles and debug anything that isn't working as you'd expect. Depending what you are trying to do, remember that this is only a development environment and it may not work correctly in a native device. If you are doing anything complicated, make sure to double check using a real device to see that everything looks good.

Notice that you will often need to use !important if you're overriding component styles directly, without using any variables. That's because the default styles are usually scoped to the Angular component, and you won't be able to provide more specificity in your selectors.

Working with colors

The main color of the app is Moodle Orange, but you can change it by using the --brand-color variable. Other than the overall brand color, there are also some specific variables for other colors.

Basic colors

These are the variables used to define the basic color palette used throughout the app:

--white and --black.
--gray, --gray-light, --gray-lighter, --gray-dark and --gray-darker.
--red, --red-light and --red-dark.
--green, --green-light and --green-dark.
--blue, --blue-light and --blue-dark.
--yellow, --yellow-light and --yellow-dark.
--purple and --turquoise (these don't define any variants).

Semantic colors

The basic colors are not used directly too often. Instead, the following semantic colors are used:

--primary (derived from --brand-color).
--danger (derived from --red).
--warning (derived from --yellow).
--success (derived from --green).
--info (derived from --blue).
--light (derived from --gray-lighter).
--medium (derived from --gray-light).
--dark (derived from --black).

Each of these also define other variants: rgb, contrast, contrast-rgb, shade and tint. If you want to modify any of these, it won't suffice with changing the base color they are derived from, because there are limitations and you'll have to override each variant manually.

For example, if you want to override the primary color, you'll need to override the following variables:

body {
    --ion-color-primary: #006600;

    /* RGB list of the color */
    --ion-color-primary-rgb: 0,102,0;

    /* Black or white, depending on which color gives more contrast */
    --ion-color-primary-contrast: #ffffff;

    /* RGB version of the contrast color */
    --ion-color-primary-contrast-rgb: 255,255,255;

    /* Slightly darker color. (mix 12% of black) */
    --ion-color-primary-shade: #005a00;

    /* Slightly lighter color. (mix 10% of white) */
    --ion-color-primary-tint: #1a751a;
}

Specific colors

Other than the basic and semantic colors, other components and pages define their own variables that you can override. You can look at the source code to find more, but these are some of the most relevant:

body {
    /* Page background */
    --background-color: white;
    --ion-background-color-rgb: 255, 255, 255;

    /* Main text color */
    --text-color: black;
    --ion-text-color-rgb: 0, 0, 0;

    /* Text used in categories and secondary content */
    --subdued-text-color: gray;

    /* Links text */
    --core-link-color: blue;
}

Targeting different environments

The html and body elements contain classes that indicate the environment the app is running on.

Platform

The html element indicates which platform the app is running on. For example, you can specify styles that will only apply to iOS by prepending them with html.ios, or html.md for Android:

/* Red toolbar in iOS */
html.ios body {
    --core-header-toolbar-background: red;
}

/* Green toolbar in Android */
html.md body {
    --core-header-toolbar-background: green;
}

Moodle App and Moodle site versions

The body element indicates the versions of the app and the Moodle site, so you can restrict CSS rules to a specific version by prepending one of these classes to the selector. For example, when accessing a 3.11.2 site using the 3.9.5 app the following classes will be present in the body:

version-3
version-3-11
version-3-11-2
moodleapp-3
moodleapp-3-9
moodleapp-3-9-5

And here's how to use them:

/* Red toolbar for Moodle App version 3.9.X */
body.moodleapp-3-9 {
    --core-header-toolbar-background: red;
}

/* Green toolbar for all other versions */
body {
    --core-header-toolbar-background: green;
}

Application theme

The application uses a light theme by default, but it adds the dark class to the body element when it is using a dark theme:

/* Red toolbar for the Light Theme */
body {
    --core-header-toolbar-background: red;
}

/* Green toolbar for the Dark Theme */
body.dark {
    --core-header-toolbar-background: green;
}

Bear in mind that you can disable Dark Mode for all your users following the guide for admins (Disabled features).

Combining classes

Of course, you can combine any of these classes to create more granular styles.

Let's say you want to have a red toolbar only in iOS, with the Dark Theme, for a Moodle site running 3.11.X:

html.ios body.version-3-11.dark {
    --core-header-toolbar-background: red;
}

Styling the Shadow DOM

Ionic is a set of web components, and uses the Shadow DOM to encapsulate them and make them more opaque to developers and users (hiding markup structure, style, and behavior), thus avoiding conflicts with existing rules.

This makes it more difficult to personalise and change some parts of those components. However you can check the official Ionic documentation to see which parts are customisable.

For example, if you look at the documentation for an ion-button, you can style it this way:

/* Disable text transformations */
ion-button::part(native) {
    text-transform: none;
}

/* Use a red background by default */
ion-button {
    --background: red;
}

/* Use a yellow background for buttons with the "my-custom-class" class */
ion-button.my-custom-class {
    --background: yellow;
}

You can learn more about the Shadow DOM in the following resources:

Supporting older versions of the app

If you need to support different versions of the app, or you're upgrading your theme from an older version, you should read the Moodle App Remote Themes Upgrade Guide.

Common customisations

In this section you will find a list of some common customisations you may want to add to your Remote Theme.

Header toolbar

The header toolbar has a bottom border that you can disable or customise, along with other parts:

/* Background */
ion-header ion-toolbar {
    --core-header-toolbar-background: red;
}

/* Bottom border */
ion-header ion-toolbar {
    --core-header-toolbar-border-width: 2px; /* Use 0 to disable it */
    --core-header-toolbar-border-color: green;
}

/* Text and buttons */
ion-header ion-toolbar {
    --core-header-toolbar-color: blue;
}

ion-header ion-toolbar.in-toolbar h1,
ion-header ion-toolbar.in-toolbar h2 {
    font-weight: normal;
}

Bottom tab bar (main menu)

ion-tab-bar.mainmenu-tabs {
    /* Background */
    --core-bottom-tabs-background: red;
    --core-bottom-tabs-background-selected: transparent;

    /* Tab icons */
    --core-bottom-tabs-color: blue;

    /* Selected tab icon */
    --core-bottom-tabs-color-selected: green;

    /* Badges */
    --core-bottom-tabs-badge-text-color: black;
    --core-bottom-tabs-badge-color: white;
}

Top tabs

core-tabs, core-tabs-outlet {
    /* Background */
    --core-tabs-background: red;

    /* Tab */
    --core-tab-background: red;
    --core-tab-color: white;

    /* Selected tab */
    --core-tab-color-active: blue;
    --core-tab-border-color-active: blue;
    --core-tab-font-weight-active: bold;
}

Items

body {
    /* Background */
    --ion-item-background: green;

    /* Divider */
    --item-divider-background: red;
    --item-divider-color: blue;

    /* Empty Divider */
    --spacer-background: yellow;
}

Progress bar

core-progress-bar {
    --core-progressbar-height: 4px;
    --core-progressbar-color: red;
    --core-progressbar-text-color: green;
    --core-progressbar-background: blue;
}

More page

/* Icons */
page-core-mainmenu-more {
    --core-more-icon: red;
}

/* Target a specific icon */
page-core-mainmenu-more .addon-privatefiles-handler ion-icon {
    color: green !important;
}

/* Items */
page-core-mainmenu-more {
    --core-more-item-border: blue;
    --spacer-background: blue;
}

Login page

You can personalise some colors in the Login page, but keep in mind that this only includes the credentials page (the one after you select the site).

body {
    --core-login-background: red;
    --core-login-text-color: blue;
    --core-login-input-background: green;
    --core-login-input-color: yellow;
}

Calendar page

body {
    --addon-calendar-event-category-color: purple;
    --addon-calendar-event-course-color: red;
    --addon-calendar-event-group-color: yellow;
    --addon-calendar-event-user-color: blue;
    --addon-calendar-event-site-color: green;
    --addon-calendar-today-border-color: orange;
    --addon-calendar-border-color: gray;
}

Messages page

body {
    --addon-messages-message-bg: white;
    --addon-messages-message-activated-bg: gray-light;
    --addon-messages-message-note-text: gray-dark;
    --addon-messages-message-mine-bg: gray-light;
    --addon-messages-message-mine-activated-bg: gray;
    --addon-messages-discussion-badge: orange;
    --addon-messages-discussion-badge-text: white;
    --core-send-message-input-background: gray-light;
    --core-send-message-input-color: black;
}

Showing course summary image on course page

By default, course summary images are hidden to reduce scrolling when entering a course. If you want to change this behaviour, you can include the following CSS in your Remote Theme:

ion-app core-course-format .core-format-progress-list .core-course-thumb {
    display: block !important;
}

Updating your theme after release

Once you have configured your theme, some users may already have downloaded previous styles and they will be cached.

If you are updating the styles and you want users to get the latest version, you can change the url of the theme file. This doesn't mean that you need to change the name of the file itself, you can just add some query parameters that will be irrelevant when the file is downloaded:

https://mysite.com/mobile/mobiletheme.css?version=1

Every time you make some changes in your theme and you want the file to be re-downloaded in the app, just increase this number.

Difference between Remote Themes and Branded Apps

Remote Theme styles can be tricky to modify. There are lots of CSS rules and some of them can change between versions. Using your own Branded App, you will have better integrations because you can also use Sass variables to change colors and styles. Additionally, you will get your custom application icon and the theming will cover the entire application, not just pages using your site.

You can find more info on the Branded Apps page.

Documentation