Comprehensive Theming#
Any application, including Otto, can be loosely divided into two parts:
the user interface (“how it looks”),
and the application logic (“how it works”).
For example, when considering a product in Otto, the user interface consists of how the products are laid out on the page, how the selectors look, how the checkout button is labelled, what sort of fonts and colors are used to display the text, and so on. The application logic consists of how Otto adjusts product price based on the discount coupons, and how it records that information to be displayed in the future.
Theming consists of changing the user interface without changing the application logic. When setting up an E-Commerce website, the website operator often wants to use their own logo, modify the color scheme, change links in the header and footer for SEO (search engine optimization) purposes, and so on. However, although the user interface may look different, the application logic must remain the same so that Otto continues to work properly. A well-designed theme preserves the general layout and structure of the user interface, so that users of the website still find it familiar and easy to use. Be careful about making sweeping changes to the user interface without warning: your users will be very confused!
Note
Comprehensive Theming can be disabled by setting ENABLE_COMPREHENSIVE_THEMING
to False
.
ENABLE_COMPREHENSIVE_THEMING = False
Theme Structure#
From a technical perspective, theming consists of overriding core
Templates,
Static Assets and
Sass
with themed versions of those resources. Every theme must conform to a directory structure. This structure mirrors the Otto directory structure and looks like this
my-theme
├── README.rst
├── static
| └── images
| | └── logo.png
| |
| └── sass
| └── partials
| └── utilities
| └── _variables.scss
|
└── templates
└── oscar
| └── dashboard
| └── index.html
└── 404.html
Templates#
Any template included in ecommerce/templates
directory is themable. However, make sure not to override
class names or id values of html elements inside a template, as these are used by javascript and/or css and overriding
these could cause unwanted behavior.
Static Assets#
Any static asset included in ecommerce/static
can be overridden except css files present in ecommerce/static/css
.
Css styles can be overridden via sass overrides explained below.
Caution
Theme names should be unique and no static asset and/or directory name should be same as theme’s name. Otherwise static assets would not work correctly.
Sass#
Sass overrides are a little different from static asset or template overrides.
There are two types of styles included in ecommerce/static/sass
:
base
partials
Warning
Styles present in ecommerce/static/sass/base
should not be overridden as overriding these
could result in an unexpected behavior.
Any styles included in ecommerce/static/sass/partials
can be overridden.
Styles included in this directory contain variable definitions that are used by main sass files. This is the best place
if you want to update things like header/footer background, fonts etc.
Enabling a Theme#
To enable a theme, you must first install your theme onto the same server that is running Otto.
If you are using devstack or fullstack to run Otto, you must be sure that the theme is present on the Vagrant virtual machine.
It is up to you where to install the theme on the server, but a good default location is /edx/app/ecommerce/ecommerce/themes
.
Note
All themes must reside in the same physical directory.
In order for Otto to use the installed themes, you must specify the location of the theme directory in Django settings by setting COMPREHENSIVE_THEME_DIRS in your settings file:
COMPREHENSIVE_THEME_DIRS = ["/edx/app/ecommerce/ecommerce/themes", ]
Where /edx/app/ecommerce/ecommerce/themes
is the path to where you have installed the
themes on your server. You can list any/all theme directories through this setting.
After installing a theme, it is associated with sites by adding appropriate entries to the following tables
Site
Site Themes
for local devstack, if Otto server is running at localhost:8002
you can enable a my-theme
by
Adding a new site with domain
localhost:8002
and name “Otto My Theme”and a site theme with Theme dir name
my-theme
and selectinglocalhost:8002
from site dropdown.
Otto server can now be started, and my-theme
should be applied now. If you have overridden sass styles and you are not
seeing those overrides then you need to compile sass files as discussed in Compiling Theme Sass.
Disabling a Theme#
Theme can be disabled by removing its corresponding Site Theme
entry using django admin.
Creating or Updating Site and SiteTheme#
If you have already setup COMPREHENSIVE_THEME_DIRS
then you can use management command for adding
Site
and SiteTheme
directly from the terminal.
python manage.py create_or_update_site_theme --site-domain=localhost:8002 --site-name=localhost:8002 --site-theme=my-theme
create_or_update_site_theme
accepts the following optional arguments
- –settings:
settings file to use,
default: ecommerce.settings.devstack
python manage.py create_or_update_site_theme --settings=ecommerce.settings.production- –site-id:
id of the site that you want to update
# update domain of the site with id 1 and add a new theme ``my-theme`` for this site python manage.py create_or_update_site_theme --site-id=1 --site-domain=my-theme.localhost:8002 --site-name=my-theme.localhost:8002 --site-theme=my-theme- –site-domain:
domain of the site to be created,
python manage.py create_or_update_site_theme --site-domain=localhost:8002 --site-theme=my-theme- –site-name:
Name of the site to be created,
default: ''
python manage.py create_or_update_site_theme --site-domain=localhost:8002 --site-name=localhost:8002 --site-theme=my-theme- –site-theme:
theme dir for the new theme,
python manage.py create_or_update_site_theme --site-domain=localhost:8002 --site-name=localhost:8002 --site-theme=my-theme
Compiling Theme Sass#
Management command update_assets
can be used for compiling and collecting themed sass.
python manage.py update_assets
update_assets
accepts the following optional arguments
- –settings:
settings file to use,
default: ecommerce.settings.devstack
python manage.py update_assets --settings=ecommerce.settings.production- –themes:
Space separated list of themes to compile sass for. ‘all’ for all themes, ‘no’ to skip sass compilation for themes,
default: 'all'
# compile sass for all themes python manage.py update_assets --theme=all # compile sass for only given themes, useful for situations if you have installed a new theme # and want to compile sass for just this theme python manage.py update_assets --themes my-theme second-theme third-theme # skip sass compilation for themes, useful for testing changes to system # sass, keeping theme styles unchanged python manage.py update_assets --theme=no- –output-style:
Coding style for compiled css files. Possible options are
nested
,expanded
,compact
andcompressed
.default: 'nested'
python manage.py update_assets --output-style='compressed'- –skip-system:
This flag disables system sass compilation.
# useful in cases where you have updated theme sass and system sass is unchanged. python manage.py update_assets --skip-system- –enable-source-comments:
This flag enables source comments in generated css files
python manage.py update_assets --enable-source-comments- –skip-collect:
This flag can be used to skip collectstatic call after sass compilation
# useful if you just want to compile sass, and collectstatic would later be called, may be by a script python manage.py update_assets --skip-collect
Troubleshooting#
If you have gone through the above procedure and you are not seeing theme overrides, you need to make sure
COMPREHENSIVE_THEME_DIRS
must contain path for the directory containing themes e.g. if your theme is/edx/app/ecommerce/ecommerce/themes/my-theme
then correct value forCOMPREHENSIVE_THEME_DIRS
is['/edx/app/ecommerce/ecommerce/themes']
.domain
name for site is the name users will put in the browser to access the site, it also includes port number e.g. if Otto is running onlocalhost:8002
then domain should belocalhost:8002
Theme dir name is the name of the directory of you theme, for our ongoing example
my-theme
is the correct theme dir name.