Moodle App Remote Themes

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 customized 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 customize the UI, you'll need to do different things.

The application defines some CSS properties that can help you customize 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.

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 personalize and change some parts of those components. However you can check the official Ionic documentation to see which parts are customizable.

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:

• Using shadow DOM - Web Components | MDN
• CSS Shadow Parts - Ionic Documentation
• Shadow DOM in Ionic (and Why it's Awesome) - Ionic Blog

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;
}

Notice how we needed to use !important in this case. That's something you'll see often if you override component styles, because the default styles are usually scoped to the Angular component and you won't be able to provide more specificity in your selector.

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.

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.