Enabling and Applying Themes

Enabling and Applying Themes#

Tags: site operator

You must enable the use of themes for your Open edX installation before you can apply themes to your Open edX sites. If your installation has only one site, you apply a theme to that default site.

For more information about Open edX sites, see Configuring Open edX Sites.

Enable Themes#

To enable the use of themes for your Open edX installation, follow these steps.

  1. Create an installation-wide themes directory to hold the customized UI files for all of the themes that you create. This directory will hold subdirectories for each theme. Your Open edX installation will look in the directory to find the themes you apply to sites.

    You can create this directory at any location on a file system that is accessible to your Open edX installation. For example, you might place it at the root of the file system in a directory named /my-open-edx-themes.

  2. Set the file permissions on the themes directory, and all of its subdirectories, to enable read+write permissions for the Ubuntu user.

    For example, to allow the devstack edxapp user for the LMS and Studio to read and write files in the themes directory, you might use the following commands.

    sudo chown -R edxapp:edxapp /my-open-edx-themes
sudo chmod -R u+rw /my-open-edx-themes

    On fullstack and native installations the Ubuntu user is www-data.

  3. For each Open edX component that you want to theme, set the ENABLE_COMPREHENSIVE_THEMING configuration property to true.

    The specific method that you use to configure Open edX components depends on the type of environment you are using. For example, you can set the configuration property in the following files.

    • For the LMS, you edit /edx/app/edxapp/lms.yml to set "ENABLE_COMPREHENSIVE_THEMING": true.

    • For Studio, you edit /edx/app/edxapp/studio.yml to set "ENABLE_COMPREHENSIVE_THEMING": true.

    • For the E-commerce service, you edit /edx/etc/ecommerce.yml to set ENABLE_COMPREHENSIVE_THEMING: true.

    If any of these files do not exist, you can add them to define this configuration setting.

  4. For each Open edX component that you want to apply a theme to, add the absolute path of the themes directory to the COMPREHENSIVE_THEME_DIRS configuration property.

    The specific method that you use to configure Open edX components depends on the type of environment you are using. For example, you can set the configuration property in the following files.

    • For Studio, add the path to COMPREHENSIVE_THEME_DIRS in /edx/app/edxapp/studio.yml.

      "COMPREHENSIVE_THEME_DIRS": [
    "/my-open-edx-themes/edx-platform"

],

    • For the LMS, add the path to COMPREHENSIVE_THEME_DIRS in /edx/app/edxapp/lms.yml.

      "COMPREHENSIVE_THEME_DIRS": [
    "/my-open-edx-themes/edx-platform"
],

    • For the E-commerce service, add the path to COMPREHENSIVE_THEME_DIRS in /edx/etc/ecommerce.yml.

      COMPREHENSIVE_THEME_DIRS: ["/my-open-edx-themes/ecommerce"]

  5. Restart all servers.

Note

You can create more than one themes directory for your Open edX installation. To use multiple themes directories, include the path to each directory in the COMPREHENSIVE_THEME_DIRS configuration property. The following example shows the configuration for multiple themes directories.

"COMPREHENSIVE_THEME_DIRS": [
    "/my-open-edx-themes/edx-platform",
    "/my-other-open-edx-themes/edx-platform"
],

Example Settings for Comprehensive Theme#

For the following file structure:

edx
└── my-themes
   └── my-theme-red
        ├── cms
        └── lms
           └── static
           └── templates

set these in lms.yml and studio.yml:

"COMPREHENSIVE_THEME_DIRS": [
    "/edx/my-themes",
],
"THEME_NAME": "my-theme-red"

Apply a Theme to a Site#

To apply a theme to an Open edX site, follow these steps.

  1. Make sure that you have enabled theming for your Open edX installation and that you have configured an installation-wide themes directory. For more information, see Enabling and Applying Themes.

  2. Make sure that you have created a theme and that you know the identifier of the theme. The identifier of a theme is the name of the directory for that theme, within your installation-wide themes directory. For more information, see Creating a Theme.

  3. Sign in to the Django administration console for your base URL. For example, http://{your_URL}/admin.

  4. Select Site themes.

  5. Select Add site theme.

  6. From the Site menu, select the site you want to apply a theme to.

  7. In the Theme dir name field, enter the identifier of the theme.

  8. Select Save.

Maintenance Chart

Review Date

Working Group Reviewer

Release

Test situation
Contents