Open edX Comprehensive Theming

edX › Code
Django, code, edX

Note: This is for my research purpose.

Comprehensive Theming lets you customize the appearance of your Open edX installation. You can override Sass and CSS settings, images, or entire HTML templates.

Eventually, Comprehensive Theming will obsolete existing theming mechanisms, but for now they co-exist peacefully. This document describes how to use Comprehensive Theming, and also the changes you’ll need to make to keep other theming mechanisms working.

Creating a theme

A theme is a directory of assets. You can create this directory wherever you like, it does not have to be inside the edx-platform directory. The structure within this directory mirrors the assets in the edx-platform repo itself. Files you provide in your theme are used in place of the same-named files in edx-platform. Here’s a sample:

my-theme
└── lms
    ├── static
    │   ├── images
    │   │   └── logo.png
    │   └── sass
    │       ├── _overrides.scss
    │       ├── lms-main-rtl.scss
    │       └── lms-main.scss
    └── templates
        ├── footer.html
        └── header.html

The top directory is named whatever you like. This example uses “my-theme”. The files provided here override the files in edx-platform. In this case, the my-theme/lms/static/sass/lms-main.scss file is used in place of the edx-platform/lms/static/sass/lms-main.scss file.

Images

Images can be substituted simply by placing the new image at the right place in the theme directory. In our example above, the lms/static images/logo.png image is overridden.

Sass/CSS

Most CSS styling in Open edX is done with Sass files compiled to CSS. You can override individual settings by creating a new Sass file that uses the existing file, and overrides the few settings you want.

For example, to change the fonts used throughout the site, you can create an lms/static/sass/_overrides.scss file with the change you want:

$sans-serif: 'Helvetica';

The variables that can currently be overridden are defined in
lms/static/sass/base/_variables.scss.

Note: We are currently in the middle of a re-engineering of the Sass
variables. They will change in the future. If you are interested, you can see the new development in the edX Pattern Library

Then create lms/static/sass/lms-main.scss to use those overrides, and also the rest of the definitions from the original file::

// Our overrides for settings we want to change.
@import 'overrides';

// Import the original styles from edx-platform.
@import 'lms/static/sass/lms-main';

Do this for each .scss file your site needs.

HTML Templates

You can make changes to HTML templates by copying them to your theme directory in the appropriate place, and making the changes you need. Keep in mind that in the future if you upgrade the Open edX code, you may have to update the copied template in your theme also.

Template Names

Here are the list of template names that you should use in your comprehensive theme (so far):

  • header.html
  • footer.html

You should not use the following names in your comprehensive theme:

  • themable-footer.html

If you look at the main.html template file, you will notice that it includes
header.html and themable-footer.html, rather than footer.html.
You might be inclined to override themable-footer.html as a result. DO NOT DO THIS. themable-footer.html is an additional layer of indirection that is necessary to avoid breaking microsites, which also refers to a file named footer.html. The goal is to eventually make comprehensive theming do everything that microsites does now, and then deprecate and remove microsites from the codebase. At that point, the themable-footer.html file will go away, since the additional layer of indirection will no longer be necessary.

Installing your theme

To use your theme, you need to add a configuration value pointing to your theme directory. There are two ways to do this.

  1. If you usually edit server-vars.yml:

    i. As the vagrant user, edit (or create) /edx/app/edx_ansible/server-vars.yml to add the edxapp_comprehensive_theme_dir value:

    edxapp_comprehensive_theme_dir: '/full/path/to/my-theme'

    ii. Run the update script

    $ sudo /edx/bin/update configuration master
$ sudo /edx/bin/update edx-platform HEADcomprehenisve

  1. Otherwise, edit the /edx/app/edxapp/lms.env.json file to add the COMPREHENSIVE_THEME_DIR value:

    "COMPREHENSIVE_THEME_DIR": "/full/path/to/my-theme",

Restart your site. Your changes should now be visible.

Comprehensive Theming

  • The PROFILE_IMAGE_DEFAULT_FILENAME Django setting is now ignored.

“Stanford” theming

If you want to continue using the “Stanford” theming system, there are a few changes you’ll need to make.

Create the following new files in the sass directory of your theme:

  • lms-main.scss
  • lms-main-rtl.scss
  • lms-course.scss
  • lms-course-rtl.scss
  • lms-footer.scss
  • lms-footer-rtl.scss

The contents of each of these files will be very similar. Here’s what
lms-main.scss should look like::

$static-path: '../../../..';
@import 'lms/static/sass/lms-main';
@import '_default';

Each file should set the $static-path variable to a relative path that
points to the lms/static directory inside of edx-platform. Then,
it should @import the sass file under lms/static/sass that matches
its name: lms-footer.scss should import lms/static/sass/lms-footer,
for example. Finally, the file should import the _default name, which
refers to the _default.scss Sass file that should already exist in your
Stanford theme directory.

If your theme uses a different name than “default”, you’ll need to use that
name in the @import line.

Run the update_assets command to recompile the theme::

$ paver update_assets lms --settings=aws

Microsites

If you want to continue using the “Microsites” theming system, there are a few changes you’ll need to make. A few templates have been renamed, or folded into other templates:

  • header_extra.html has been renamed to head-extra.html. This file
    was always inserted into the <head> element of the page, rather than
    the header of the <body> element, so this change makes the name more accurate.

  • google_analytics.html has been removed. The contents of this template can and should be added to the head-extra.html template.

  • google_tag_manager.html has been renamed to body-initial.html.

In addition, there are some other changes you’ll need to make:

  • The google_analytics_file config value is now ignored. If your Open edX installation has a Google Analytics account ID set, the Google Analytics JavaScript will be included automatically on your site using that account ID. You can set this account ID either using the "GOOGLE_ANALYTICS_ACCOUNT" value in the Django settings, or by setting the newly-added "GOOGLE_ANALYTICS_ACCOUNT" config value in your microsite configuration.

  • If you don’t want the Google Analytics JavaScript to be output at all in your microsite, set the "GOOGLE_ANALYTICS_ACCOUNT" config value to the empty string. If you want to customize the way that Google Analytics is loaded, set the "GOOGLE_ANALYTICS_ACCOUNT" config value to the empty string, and then load Google Analytics yourself (with whatever customizations you want) in your head-extra.html template.

  • The css_overrides_file config value is now ignored. To add a CSS override file to your microsite, create a head-extra.html template with the following content:

<%namespace name='static' file='../../static_content.html'/>
<%! from microsite_configuration import microsite %>
<% style_overrides_file = microsite.get_value('css_overrides_file') %>
% if style_overrides_file:
<link rel="stylesheet" type="text/css" href="${static.url(style_overrides_file)}" />
% endif

If you already have a head-extra.html template, you can modify it to
output this <link rel="stylesheet"> tag, in addition to whatever else you already have in that template.

Source: https://github.com/edx/edx-platform