Open edX Custom Theming Tutorial

Open edX’s Comprehensive Theming Framework (also known as “Stanford Theming”) provides a powerful and infinitely flexible way for you to tailor your user interface to your unique needs. By leveraging the comprehensive theming framework as opposed to directly editing UI source code you’ll also be able to better manage your customizations and protect your work from the risks of being overwritten whenever you upgrade your Open edX platform.

Note that there is good system documentation located on your Open edX installation Ubuntu file system: /edx/app/edxapp/edx-platform/themes/README.rst, and also in the Open edX Official documentation.

The basic software pattern for Open edX’s comprehensive theming framework is refreshingly similar to theming systems with which you might already be familiar, such as Drupal and WordPress. In the case of Open edX, the platform ships with a default theme that is preloaded with the standard “Native Build” installation. If no alternative theme is specified, as is the case when you’ve only just installed the platform, then Open edX renders the UI using the files from the default theme. Once comprehensive theming has been enabled then Open edX will first look for files in the custom theme folders, reverting to the files from the default theme only in cases where files were not found in the custom theme folder.

Let’s take a look at this in practice. Suppose the the Open edX web browser needs two files: the logo png file, and the header.html file. Let’s furthermore assume that we’ve modified the logo png file in our custom theme but we’ve made no other changes to the header of our site. Here is how the comprehensive theming system will evaluate these file requests:

The comprehensive theming framework elegantly determines the correct combination of source files using this very simple 2-factor search protocol. Bear in mind however that this evaluation is NOT done on a real-time basis as you might expect. On the contrary, in the case of Open edX the UI files must be compiled, which is a multi-step process that deals with a host of UI related technologies so that at run-time the Nginx web server only has to work with pure HTML, CSS, Javascript and media assets. We’ll look at this in more detail below.

The default theme is enormous, containing nearly 2,000 source files combined between the Learning Management System (LMS) and the Course Management Studio (CMS). Fortunately however you’ll probably only need to modify a dozen or so. The reasoning behind this is pretty simple: the header and footer makeup the bulk of the content areas that most organizations want to customize, and these areas of the platform are rendered with a limited set of source files, as follows:

Lets take a closer look at some of the contents of the default theme files and folders. Take note of the highlighted files as these are the most commonly customized parts of the default theme.

By following this procedure you should be able to enable comprehensive theming working in around one hour. The steps we will complete:

1. Fork my Github repository edx.custom-theme
2. Clone the repository to the home folder of your EC2 Ubuntu instance
3. Edit /edx/etc/lms.yml
4. Compile static assets
5. Restart the Open edX LMS and CMS

1. Fork my GitHub repository

This repository should save you some time and potential confusion getting everything setup. This repository contains an empty theme, and so it won’t change your UI in any way. However, it does include the correct folder structure as per the framework’s technical requirements. I struggled with this the first time created a custom Open edX theme, which is why i eventually created and began using this template. The repository is located here: https://github.com/lpm0073/edx.custom-theme

Note: you’ll need to create a free Github account if you don’t already have one.

Once you’ve forked the repository the basic idea is that you’ll manage this like any other software development project. You’ll copy source files from the Open edX default theme into your repository folders, and then permanently manage these files using Github as your source control system and code repository.

2. Clone Repository To Your EC2 Ubuntu Instance

SSH into your Open edX Ubuntu instance and then clone your repository into the home directory. For this tutorial I’m going to use the path to my own original edx.custom-theme repository, so make sure that you edit the path information so that these commands point to your forked repository.

Update September 24, 2018: Please take note that on my most recent installation of Hawthorn I was unable to compile static assets after cloning the sample theme into my home folder. Instead, I had to move the theme folder to /edx/app/edxapp/edx-platform/themes, where incidentally you’ll find a set of additional preinstalled themes created by the Open edX team. Some of the comments below suggest that others have recently run into this same problem. This problem might work itself out in subsequent releases, so for the time being I’m leaving the original technical instructions unchanged.

[sourcecode language=”bash”]cd ~

# Change this URL to YOUR repository
git clone https://github.com/lpm0073/edx.custom-theme.git

chown edxapp -R edx.custom-theme
chgrp edxapp -R edx.custom-theme[/sourcecode]

3. Edit /edx/etc/lms.yml

Once again, keep in mind that these code samples reference my Github repository rather than your forked repository, so make sure you edit the path data accordingly. This file has around 400 rows of parameter values, and you’ll make edits in three different parts of the file so make sure to take note of the row numbers in the screen shots below.

Update September 24, 2018: Please also take note that if you cloned your theme into /edx/app/edxapp/edx-platform/themes then you’ll need to modify the lms.yml parameter value “COMPREHENSIVE_THEME_DIRS” accordingly.

4. Compile Static Assets

In most cases, the effects of modifying your custom theme will not take effect until you re-compile static assets. The Open edX static asset compilation process is somewhat murky to me, but so far I can confirm that it uses both Webpack and Paver to consolidate static assets into a single location (which incidentally is /edx/var/edxapp/staticfiles/) and then it encodes the files with system-generated filename suffixes, which as best I can tell is a crude way to invalidate client browser caches.

One exception to the re-compilation requirement is Mako templates, which are magically evaluated real-time. AWESOME! 

Take note that this process runs for around 15 minutes, and your Open edX platform will not be available until the process completes. Also be aware that if your theme contains any compilation errors then your Open edX platform will almost certainly break.

The commands to re-compile static assets are as follows:

[sourcecode language=”bash”]# for Hawthorn version and later

# 1. switch to Ubuntu username ‘edxapp’, and then simultaneously launch a bash shell
sudo -H -u edxapp bash

# 2. load the virtual environment for user ‘edxapp’ that is shipped with your Open edX installation
source /edx/app/edxapp/edxapp_env

# 3. switch to the Open edX "main" working directory (this is where the Paver executable as well as other Open edX utility apps are located)
cd /edx/app/edxapp/edx-platform

# 4. execute paver to recompile static assets for the LMS (Learning Management System) Django project.
# this takes between 10 and 20 minutes to run, and generates a LOT of screen output.
paver update_assets lms –settings=production

# 5. (optional step) execute paver to recompile static assets for the CMS (Course Management Studio) Django project
paver update_assets cms –settings=production

# ————————————————————————
# * If you’re running an older version of Open edX and the commands
# above do not work.
# ————————————————————————
sudo -H -u edxapp bash
source /edx/app/edxapp/edxapp_env
cd /edx/app/edxapp/edx-platform
paver update_assets lms –settings=aws # note that ‘settings’ file is different
paver update_assets cms –settings=aws # note that ‘settings’ file is different
exit[/sourcecode]

5. Restart the LMS and CMS

You have to restart the LMS and CMS for two reasons.  First, you modified the Django environment configuration file lms.yml and in order for these changes to take effect the file needs to be reloaded, which is most easily accomplished by stopping and re-starting the application. Second, you recompiled static assets, and for reasons entirely unknown to me this necessitates a restart of at least the LMS (but restart both LMS and CMS just to be safe).

[sourcecode language=”bash”]# restart edx instance
/edx/bin/supervisorctl restart lms
/edx/bin/supervisorctl restart cms
/edx/bin/supervisorctl restart edxapp_worker:[/sourcecode]

If you followed the steps correctly then your Open edX platform should be running, but you should not notice any visual changes to the UI. Next you should add a file to your new custom theme and then repeat steps 2 thru 5 to verify that Open edX detects and includes your new file when it renders the UI. Changing the platform logo is a great way to get started. The platform logo file should be saved in the following location in your theme:

edx.custom-theme/themes/custom-theme/lms/static/images/logo.png

I hope you found this helpful. Please help me improve this article by leaving a comment below. Thank you!