Skip to content

Commit

Permalink
fix: brand overrides
Browse files Browse the repository at this point in the history 
docs: fix code example

docs: add missing comma

docs: update how to
  • Loading branch information
@adamstankiewicz @dcoa
adamstankiewicz authored and dcoa committed May 14, 2024
1 parent a6bae3b commit 4863b8a
Show file tree
Hide file tree
Showing 2 changed files with 314 additions and 138 deletions.
92 changes: 78 additions & 14 deletions docs/how_tos/theming.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,19 +6,25 @@ This document serves as a guide to using `@edx/frontend-platform` to support MFE

![overview of paragon theme loader](./assets/paragon-theme-loader.png "Paragon theme loader")

## Theme URL configuration
## Basic theme URL configuration

Paragon supports 2 mechanisms for configuring the Paragon theme URLs:
Paragon supports 2 mechanisms for configuring the Paragon theme urls:
* JavaScript-based configuration via `env.config.js`.
* MFE runtime configuration API via `edx-platform`

Using either configuration mechanism, a `PARAGON_THEME_URLS` configuration setting must be created to point to the externally hosted Paragon theme CSS files, e.g.:

```json
{
"core": "https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/core.css",
"core": {
"url": "https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/core.min.css"
},
"variants": {
"light": "https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/light.css"
"light": {
"url": "https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/light.min.css",
"default": true,
"dark": false,
}
}
}
```
Expand All @@ -32,16 +38,22 @@ To use this JavaScript-based configuration approach, you may set a `PARAGON_THEM
```js
const config = {
PARAGON_THEME_URLS: {
core: 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/paragon.css',
core: {
url: 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/core.min.css',
},
variants: {
light: 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/scss/core/css/variables.css',
light: {
url: 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/light.min.css',
default: true,
dark: false,
},
},
},
};

export default config;
```


### MFE runtime configuration API

`@edx/frontend-platform` additionally supports loading application configuration from the MFE runtime configuration API via `edx-platform`. The configuration is served by the `http://localhost:18000/api/mfe_config/v1` API endpoint. For more information, refer to [this documentation](https://github.com/openedx/edx-platform/blob/master/lms/djangoapps/mfe_config_api/docs/decisions/0001-mfe-config-api.rst) about the MFE runtime configuration API, please see these docs.
Expand All @@ -52,12 +64,18 @@ The application configuration may be setup via Django settings as follows:
ENABLE_MFE_CONFIG_API = True
MFE_CONFIG = {}
MFE_CONFIG_OVERRIDES = {
# `APP_ID` defined in your MFE
# The below key represented the `APP_ID` defined in your MFE
'profile': {
'PARAGON_THEME_URLS': {
'core': 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/core.css',
'core': {
'url': 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/core.min.css',
},
'variants': {
'light': 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/light.css',
'light': {
'url': 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/light.min.css',
'default': True,
'dark': False,
},
},
},
},
Expand All @@ -66,11 +84,57 @@ MFE_CONFIG_OVERRIDES = {

### Locally installed `@edx/paragon`

In the event the other Paragon CSS URLs are configured via one of the other documented mechanisms, but they fail to load (e.g., the CDN url throws a 404), `@edx/frontend-platform` will fallback to injecting the locally installed Paragon CSS from the consuming application into the HTML document.
If you would like to use the same version of the Paragon CSS urls as the locally installed `@edx/paragon`, the configuration for the Paragon CSS urls may contain a wildcard `$paragonVersion` which gets replaced with the locally installed version of `@edx/paragon` in the consuming application, e.g.:

```shell
https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/core.min.css
https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/light.min.css
```

In the event the other Paragon CSS urls are configured via one of the other documented mechanisms, but they fail to load (e.g., the CDN url throws a 404), `@edx/frontend-platform` will attempt to fallback to injecting the locally installed Paragon CSS from the consuming application into the HTML document.

## Usage with `@edx/brand`

The core Paragon design tokens and styles may be optionally overriden by utilizing `@edx/brand`, which allows theme authors to customize the default Paragon theme to match the look and feel of their custom brand.

If you would like to use the same version of the Paragon CSS URLs as the locally installed `@edx/paragon`, the configuration for the Paragon CSS URLs may contain a wildcard `$paragonVersion` which gets replaced with the locally installed version of `@edx/paragon` in the consuming application, e.g.:
This override mechanism works by compiling the design tokens defined in `@edx/brand` with the the core Paragon tokens to generate overrides to Paragon's default CSS variables, and then compiling the output CSS with any SCSS theme customizations not possible through a design token override.

The CSS urls for `@edx/brand` overrides will be applied after the core Paragon theme urls load, thus overriding any previously set CSS variables and/or styles.

To enable `@edx/brand` overrides, the `PARAGON_THEME_URLS` setting may be configured as following:

```js
const config = {
PARAGON_THEME_URLS: {
core: {
urls: {
default: 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/core.min.css',
brandOverride: 'https://cdn.jsdelivr.net/npm/@edx/brand-edx.org@#brandVersion/dist/core.min.css',
},
},
variants: {
light: {
urls: {
default: 'https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/light.min.css',
brandOverride: 'https://cdn.jsdelivr.net/npm/@edx/brand-edx.org@$brandVersion/dist/light.min.css',
},
default: true,
dark: false,
},
},
},
};

export default config;
```

### Locally installed `@edx/brand`

If you would like to use the same version of the brand override CSS urls as the locally installed `@edx/brand`, the configuration for the brand override CSS urls may contain a wildcard `$brandVersion` which gets replaced with the locally installed version of `@edx/brand` in the consuming application, e.g.:

```shell
https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/core.css
https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/scss/core/css/variables.css
https://cdn.jsdelivr.net/npm/@edx/brand@$brandVersion/dist/core.min.css
https://cdn.jsdelivr.net/npm/@edx/brand@$brandVersion/dist/light.min.css
```

In the event the other brand override CSS urls are configured via one of the other documented mechanisms, but they fail to load (e.g., the CDN is down), `@edx/frontend-platform` will attempt to fallback to injecting the locally installed brand override CSS urls from the consuming application into the HTML document.
Loading

0 comments on commit 4863b8a

Please sign in to comment.