openedx.core.djangoapps.theming package

Contents

openedx.core.djangoapps.theming package#

Subpackages#

Submodules#

openedx.core.djangoapps.theming.apps module#

class openedx.core.djangoapps.theming.apps.ThemingConfig(app_name, app_module)#

Bases: AppConfig

name = 'openedx.core.djangoapps.theming'#
plugin_app = {'url_config': {'cms.djangoapp': {'app_name': 'openedx.core.djangoapps.theming', 'namespace': 'theming', 'regex': '^theming/'}, 'lms.djangoapp': {'app_name': 'openedx.core.djangoapps.theming', 'namespace': 'theming', 'regex': '^theming/'}}}#
ready()#

Override this method in subclasses to run code when Django starts.

verbose_name = 'Theming'#

openedx.core.djangoapps.theming.checks module#

Settings validations for the theming app

openedx.core.djangoapps.theming.checks.check_comprehensive_theme_settings(app_configs, **kwargs)#

Checks the comprehensive theming theme directory settings.

Raises compatibility Errors upon:

  • COMPREHENSIVE_THEME_DIRS is not a list

  • theme dir path is not a string

  • theme dir path is not an absolute path

  • path specified in COMPREHENSIVE_THEME_DIRS does not exist

Returns:

List of any Errors.

openedx.core.djangoapps.theming.finders module#

Static file finders for Django. https://docs.djangoproject.com/en/1.8/ref/settings/#std:setting-STATICFILES_FINDERS Yes, this interface is private and undocumented, but we need to access it anyway.

In order to deploy Open edX in production, it’s important to be able to collect and process static assets: images, CSS, JS, fonts, etc. Django’s collectstatic system is the accepted way to do that in Django-based projects, but that system doesn’t handle every kind of collection and processing that web developers need. Other open source projects like Django-Pipeline and Django-Require hook into Django’s collectstatic system to provide features like minification, compression, Sass pre-processing, and require.js optimization for assets before they are pushed to production. To make sure that themed assets are collected and served by the system (in addition to core assets), we need to extend this interface, as well.

class openedx.core.djangoapps.theming.finders.ThemeFilesFinder(*args, **kwargs)#

Bases: BaseFinder

A static files finder that looks in the directory of each theme as specified in the source_dir attribute.

find(path, *args, **kwargs)#

Looks for files in the theme directories.

find_in_theme(theme, path)#

Find a requested static file in an theme’s static locations.

list(ignore_patterns)#

List all files in all app storages.

source_dir = 'static'#
storage_class#

alias of ThemeStorage

openedx.core.djangoapps.theming.helpers module#

Helpers for accessing comprehensive theming related variables.

This file is imported at startup. Imports of models or things which import models will break startup on Django 1.9+. If you need models here, please import them inside the function which uses them.

openedx.core.djangoapps.theming.helpers.current_request_has_associated_site_theme()#

True if current request has an associated SiteTheme, False otherwise.

Returns:

True if current request has an associated SiteTheme, False otherwise

openedx.core.djangoapps.theming.helpers.get_all_theme_template_dirs()#

Returns template directories for all the themes.

Example

>> get_all_theme_template_dirs() [

‘/edx/app/edxapp/edx-platform/themes/red-theme/lms/templates/’,

]

Returns:

list of directories containing theme templates.

Return type:

(list)

openedx.core.djangoapps.theming.helpers.get_config_value_from_site_or_settings(name, site=None, site_config_name=None)#

Given a configuration setting name, try to get it from the site configuration and then fall back on the settings.

If site_config_name is not specified then “name” is used as the key for both collections.

Parameters:

  • name (str) – The name of the setting to get the value of.

  • site – The site that we are trying to fetch the value for.

  • site_config_name – The name of the setting within the site configuration.

Returns:

The value stored in the configuration.

openedx.core.djangoapps.theming.helpers.get_current_request()#

Return current request instance.

Returns:

returns current request

Return type:

(HttpRequest)

openedx.core.djangoapps.theming.helpers.get_current_site()#

Return current site.

Returns:

returns current site

Return type:

(django.contrib.sites.models.Site)

openedx.core.djangoapps.theming.helpers.get_current_site_theme()#

Return current site theme object. Returns None if theming is disabled.

Returns:

site theme object for the current site.

Return type:

(ecommerce.theming.models.SiteTheme)

openedx.core.djangoapps.theming.helpers.get_current_theme()#

Return current theme object. Returns None if theming is disabled.

Returns:

site theme object for the current site.

Return type:

(ecommerce.theming.models.SiteTheme)

openedx.core.djangoapps.theming.helpers.get_project_root_name()#

Return root name for the current project

Example

>> get_project_root_name() ‘lms’ # from studio >> get_project_root_name() ‘cms’

Returns:

component name of platform e.g lms, cms

Return type:

(str)

openedx.core.djangoapps.theming.helpers.get_template_path(relative_path, **kwargs)#

The calculated value is cached for the lifetime of the current request.

openedx.core.djangoapps.theming.helpers.get_template_path_with_theme(relative_path)#

Returns template path in current site’s theme if it finds one there otherwise returns same path.

Example

>> get_template_path_with_theme(‘header.html’) ‘/red-theme/lms/templates/header.html’

Parameters:

relative_path (str) – template’s path relative to the templates directory e.g. ‘footer.html’

Returns:

template path in current site’s theme

Return type:

(str)

openedx.core.djangoapps.theming.helpers.get_theme_base_dir(theme_dir_name, suppress_error=False)#

Returns absolute path to the directory that contains the given theme.

Parameters:

  • theme_dir_name (str) – theme directory name to get base path for

  • suppress_error (bool) – if True function will return None if theme is not found instead of raising an error

Returns:

Base directory that contains the given theme

Return type:

(str)

openedx.core.djangoapps.theming.helpers.get_theme_base_dirs()#

Return base directories that contains all the themes. Ensures comprehensive theming is enabled.

Example

>> get_theme_base_dirs() [‘/edx/app/ecommerce/ecommerce/themes’]

Returns:

Base theme directory paths

Return type:

(List of Paths)

openedx.core.djangoapps.theming.helpers.get_theme_base_dirs_unchecked()#

Return base directories that contains all the themes.

Example

>> get_theme_base_dirs_unchecked() [‘/edx/app/ecommerce/ecommerce/themes’]

Returns:

Base theme directory paths

Return type:

(List of Paths)

openedx.core.djangoapps.theming.helpers.get_themes(themes_dir=None)#

get a list of all themes known to the system.

Parameters:

themes_dir (str) – (Optional) Path to themes base directory

Returns:

list of themes known to the system.

openedx.core.djangoapps.theming.helpers.is_comprehensive_theming_enabled()#

Returns boolean indicating whether comprehensive theming functionality is enabled or disabled. .. rubric:: Example

>> is_comprehensive_theming_enabled() True

Returns:

True if comprehensive theming is enabled else False

Return type:

(bool)

openedx.core.djangoapps.theming.helpers.is_request_in_themed_site()#

This is a proxy function to site_configuration.

openedx.core.djangoapps.theming.helpers.strip_site_theme_templates_path(uri)#

Remove site template theme path from the uri.

Example

>> strip_site_theme_templates_path(‘/red-theme/lms/templates/header.html’) ‘header.html’

Parameters:

uri (str) – template path from which to remove site theme path. e.g. ‘/red-theme/lms/templates/header.html’

Returns:

template path with site theme path removed.

Return type:

(str)

openedx.core.djangoapps.theming.helpers.theme_exists(theme_name, themes_dir=None)#

Returns True if a theme exists with the specified name.

openedx.core.djangoapps.theming.helpers_dirs module#

Code which dynamically discovers comprehensive themes. Deliberately uses no Django settings, as the discovery happens during the initial setup of Django settings.

class openedx.core.djangoapps.theming.helpers_dirs.Theme(name='', theme_dir_name='', themes_base_dir=None, project_root=None)#

Bases: object

class to encapsulate theme related information.

name = ''#
property path#

Get absolute path of the directory that contains current theme’s templates, static assets etc.

Returns:

absolute path to current theme’s contents

Return type:

Path

project_root = None#
property template_dirs#

Get a list of all template directories for current theme.

Returns:

list of all template directories for current theme.

Return type:

list

property template_path#

Get absolute path of current theme’s template directory.

Returns:

absolute path to current theme’s template directory

Return type:

Path

theme_dir_name = ''#
themes_base_dir = None#
openedx.core.djangoapps.theming.helpers_dirs.get_project_root_name_from_settings(project_root)#

Return root name for the current project

Example

>> get_project_root_name() ‘lms’ # from studio >> get_project_root_name() ‘cms’

Parameters:

project_root (str) – Root directory of the project.

Returns:

component name of platform e.g lms, cms

Return type:

(str)

openedx.core.djangoapps.theming.helpers_dirs.get_theme_base_dirs_from_settings(theme_base_dirs=None)#

Return base directories that contains all the themes.

Example

>> get_theme_base_dirs_from_settings(‘/edx/app/ecommerce/ecommerce/themes’) [‘/edx/app/ecommerce/ecommerce/themes’]

Parameters:

themes_base_dirs (list of str) – Paths to themes base directories.

Returns:

Base theme directory paths

Return type:

(List of Paths)

openedx.core.djangoapps.theming.helpers_dirs.get_theme_dirs(themes_base_dir=None)#

Get all the theme dirs directly under a given base dir.

Parameters:

themes_base_dir (Path) – base dir that contains themes.

Returns:

List of theme dir names (relative to the base dir) or empty list if the base themes dir does not exist or there are no containing theme dirs.

openedx.core.djangoapps.theming.helpers_dirs.get_themes_unchecked(themes_base_dirs, project_root=None)#

Returns a list of all themes known to the system.

Parameters:

  • themes_base_dirs (list of str / list of Path) – Paths to themes base directories.

  • project_root (str) – (optional) Path to project root

Returns:

List of themes known to the system.

Return type:

(list of Theme)

openedx.core.djangoapps.theming.helpers_dirs.is_theme_dir(_dir)#

Returns true if given dir contains theme overrides. A theme dir must have subdirectory ‘lms’ or ‘cms’ or both.

Parameters:

_dir – directory path to check for a theme

Returns:

Returns true if given dir is a theme directory.

openedx.core.djangoapps.theming.helpers_static module#

openedx.core.djangoapps.theming.helpers_static.get_static_file_url(asset)#

Returns url of the themed asset if asset is not themed than returns the default asset url.

Example

>> get_static_file_url(‘css/lms-main-v1.css’) ‘/static/red-theme/css/lms-main-v1.css’

Parameters:

asset (str) – asset’s path relative to the static files directory

Returns:

static asset’s url

Return type:

(str)

openedx.core.djangoapps.theming.middleware module#

Middleware for theming app

Note

This middleware depends on “django_sites_extensions” app So it must be added to INSTALLED_APPS in django settings files.

class openedx.core.djangoapps.theming.middleware.CurrentSiteThemeMiddleware(get_response)#

Bases: MiddlewareMixin

Middleware that sets site_theme attribute to request object.

process_request(request)#

Set the request’s ‘site_theme’ attribute based upon the current user.

openedx.core.djangoapps.theming.models module#

Django models supporting the Comprehensive Theming subsystem

class openedx.core.djangoapps.theming.models.SiteTheme(*args, **kwargs)#

Bases: Model

This is where the information about the site’s theme gets stored to the db.

site field is foreignkey to django Site model theme_dir_name contains directory name having Site’s theme

exception DoesNotExist#

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned#

Bases: MultipleObjectsReturned

static get_theme(site, default=None)#

Get SiteTheme object for given site, returns default site theme if it can not find a theme for the given site and DEFAULT_SITE_THEME setting has a proper value.

Parameters:

  • site (django.contrib.sites.models.Site) – site object related to the current site.

  • default (openedx.core.djangoapps.models.SiteTheme) – site theme object to return in case there is no theme associated for the given site.

Returns:

SiteTheme object for given site or a default site passed in as the argument.

static has_theme(site)#

Returns True if given site has an associated site theme in database, returns False otherwise. Note: DEFAULT_SITE_THEME is not considered as an associated site.

Parameters:

site (django.contrib.sites.models.Site) – site object related to the current site.

Returns:

True if given site has an associated site theme in database, returns False otherwise.

id#

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <django.db.models.manager.Manager object>#
site#

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Child.parent is a ForwardManyToOneDescriptor instance.

site_id#
theme_dir_name#

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

openedx.core.djangoapps.theming.storage module#

Comprehensive Theming support for Django’s collectstatic functionality. See https://docs.djangoproject.com/en/1.8/ref/contrib/staticfiles/

class openedx.core.djangoapps.theming.storage.ThemeManifestFilesMixin(*args, manifest_storage=None, **kwargs)#

Bases: ManifestFilesMixin

Comprehensive theme aware ManifestFilesMixin. Main purpose of subclassing ManifestFilesMixin is to override the following methods. 1 - _url 2 - url_converter

_url:

This method takes asset name as argument and is responsible for adding hash to the name to support caching. This method is called during both collectstatic command and live server run.

When called during collectstatic command that name argument will be asset name inside STATIC_ROOT, for non themed assets it will be the usual path (e.g. ‘images/logo.png’) but for themed asset it will also contain themes dir prefix (e.g. ‘red-theme/images/logo.png’). So, here we check whether the themed asset exists or not, if it exists we pass the same name up in the MRO chain for further processing and if it does not exists we strip theme name and pass the new asset name to the MRO chain for further processing.

When called during server run, we get the theme dir for the current site using get_current_theme and make sure to prefix theme dir to the asset name. This is done to ensure the usage of correct hash in file name. e.g. if our red-theme overrides ‘images/logo.png’ and we do not prefix theme dir to the asset name, the hash for ‘{platform-dir}/lms/static/images/logo.png’ would be used instead of ‘{themes_base_dir}/red-theme/images/logo.png’

url_converter:

This function returns another function that is responsible for hashing urls that appear inside assets (e.g. url(“images/logo.png”) inside css). The method defined in the superclass adds a hash to file and returns relative url of the file. e.g. for url(“../images/logo.png”) it would return url(“../images/logo.790c9a5340cb.png”). However we would want it to return absolute url (e.g. url(“/static/images/logo.790c9a5340cb.png”)) so that it works properly with themes.

The overridden method here simply comments out the line that convert absolute url to relative url, hence absolute urls are used instead of relative urls.

url_converter(name, hashed_files, template=None)#

This is an override of url_converter from ManifestFilesMixin. It changes one line near the end of the method (see the NOTE) in order to return absolute urls instead of relative urls. This behavior is necessary for theme overrides, as we get 404 on assets with relative urls on a themed site.

class openedx.core.djangoapps.theming.storage.ThemeMixin(**kwargs)#

Bases: object

Comprehensive theme aware Static files storage.

prefix = None#
themed(name, theme)#

Returns True if given asset override is provided by the given theme otherwise returns False. :param name: asset name e.g. ‘images/logo.png’ :param theme: theme name e.g. ‘red-theme’, ‘edx.org’

Returns:

True if given asset override is provided by the given theme otherwise returns False

url(name)#

Returns url of the asset, themed url will be returned if the asset is themed otherwise default asset url will be returned.

Parameters:

name – name of the asset, e.g. ‘images/logo.png’

Returns:

url of the asset, e.g. ‘/static/red-theme/images/logo.png’ if current theme is red-theme and logo is provided by red-theme otherwise ‘/static/images/logo.png’

class openedx.core.djangoapps.theming.storage.ThemePipelineMixin#

Bases: PipelineMixin

Mixin to make sure themed assets are also packaged and used along with non themed assets. if a source asset for a particular package is not present then the default asset is used.

e.g. in the following package and for ‘red-theme’ ‘style-vendor’: {

‘source_filenames’: [

‘js/vendor/afontgarde/afontgarde.css’, ‘css/vendor/font-awesome.css’, ‘css/vendor/jquery.qtip.min.css’, ‘css/vendor/responsive-carousel/responsive-carousel.css’, ‘css/vendor/responsive-carousel/responsive-carousel.slide.css’,

], ‘output_filename’: ‘css/lms-style-vendor.css’

} ‘red-theme/css/vendor/responsive-carousel/responsive-carousel.css’ will be used of it exists otherwise ‘css/vendor/responsive-carousel/responsive-carousel.css’ will be used to create ‘red-theme/css/lms-style-vendor.css’

static get_themed_packages(prefix, packages)#

Update paths with the themed assets, :param prefix: theme prefix for which to update asset paths e.g. ‘red-theme’, ‘edx.org’ etc. :param packages: packages to update

Returns: list of updated paths and a boolean indicating whether any path was path or not

packing = True#
post_process(paths, dry_run=False, **options)#

This post_process hook is used to package all themed assets.

class openedx.core.djangoapps.theming.storage.ThemeStorage(*args, **kwargs)#

Bases: ThemeMixin, StaticFilesStorage

openedx.core.djangoapps.theming.template_loaders module#

Theming aware template loaders.

class openedx.core.djangoapps.theming.template_loaders.ThemeFilesystemLoader(engine, dirs=None)#

Bases: Loader

Filesystem Template loaders to pickup templates from theme directory based on the current site.

get_dirs()#

Override get_dirs method.

Make the theme templates a priority, avoiding cashing templates for django ones.

static get_theme_template_sources()#

Return template sources for the given theme and if request object is None (this would be the case for management commands) return template sources for all themes.

is_usable = True#
class openedx.core.djangoapps.theming.template_loaders.ThemeTemplateLoader(*args)#

Bases: MakoLoader

Filesystem Template loaders to pickup templates from theme directory based on the current site.

is_usable = True#

openedx.core.djangoapps.theming.urls module#

Defines URLs for theming views.

openedx.core.djangoapps.theming.views module#

Views file for theming administration.

class openedx.core.djangoapps.theming.views.ThemingAdministrationFragmentView(**kwargs)#

Bases: EdxFragmentView

Fragment view to allow a user to administer theming.

create_base_standalone_context(request, fragment, **kwargs)#

Creates the context to use when rendering a standalone page.

get(request, *args, **kwargs)#

Renders the theming admin fragment to authorized users.

post(request, **kwargs)#

Accept requests to update the theme preview.

render_to_fragment(request, course_id=None, **kwargs)#

Renders the theming administration view as a fragment.

standalone_page_title(request, fragment, **kwargs)#

Returns the page title for the standalone update page.

openedx.core.djangoapps.theming.views.get_user_preview_site_theme(request)#

Returns the preview site for the current user, or None if not set.

openedx.core.djangoapps.theming.views.set_user_preview_site_theme(request, preview_site_theme)#

Sets the current user’s preferred preview site theme.

Parameters:

  • request – the current request

  • preview_site_theme (str or SiteTheme) – the preview site theme or theme name. None can be specified to remove the preview site theme.

openedx.core.djangoapps.theming.views.themed_asset(request, path)#

Redirect to themed asset.

This view makes it easy to link to theme assets without knowing what is the currently enabled theme. For instance, applications outside of the LMS may want to link to the LMS logo.

Note that the redirect is not permanent because the theme may change from one run to the next.

openedx.core.djangoapps.theming.views.user_can_preview_themes(user)#

Returns true if the specified user is allowed to preview themes.

Module contents#

Contents