All instructions to upgrade this project from one release to the next will be documented in this file. Upgrades must be run sequentially, meaning you should not skip minor/major releases while upgrading (fix releases can be skipped).
The format is inspired from Keep a Changelog, and this project adheres to Semantic Versioning.
Before any upgrade, collect static files and run database migrations:
$ make collectstatic
$ make migrate
- Dropped support for postgres version < 12
- Dropped support for MySQL version < 8
- Add new
dashboard-splitted-card
theme scheme
dashboard-splitted-card: (
color: r-color('charcoal'),
base-shadow: 0 0 6px r-color('light-grey'),
background-color: r-color('white'),
dot-color: r-color('firebrick6'),
separator-color: r-color('grey87')
),
CourseProductItem
has been moved intoSyllabusCourseRunsList/components
folder. If you have overridden this component, you have to update your overrides.json file accordingly.JOANIE_BACKEND
must be updated.COURSE_REGEX
andJS_COURSE_REGEX
must be updated to match new api routes. Take a look at joanie connection documentation for more details.- We now using Button components from cunningham design system. They can be customise with cunningham tokens configuration. See https://openfun.github.io/cunningham/?path=/docs/getting-started-customization--docs
- scss themes variable for SaleTunnel button have been removed. These are now cunningham buttons and can be customised using cunningham-tokens.
- scss themes variable for Modal 'close button' have been removed. It is now a cunningham button and can be customised using cunningham-tokens.
- cunningham have been upgraded to 2.0.0, you can follow it's upgrade guide here: https://openfun.github.io/cunningham/?path=/docs/migrating-from-v1-to-v2--docs
- With the migration to Cunningham Button, we have to reset some bootstrap styles, so we have to add a new
scss/trumps/_bootstrap.scss
file. You have to import it in your_main.scss
file.// ... // Import bootstrap reset @import 'richie-education/scss/trumps/bootstrap';
- Delete richie Button component now that we use cunningham Button component.
*_detail.html
django templates have been updated to use new course-glimpse-list structure. If have overridden those templates, you must update them. (https://github.com/openfun/richie/pull/2069/commits/e36fa58a579c3b58384baf896fcf4b7579a46342)- In
_theme.scss
,steps-content
map has one more propertysummary-hover-color
, if you have overriden this map, you must add this new property.
- Within course_detail template, course runs list is now rendered as a React widget. As consequence
fragment_course_run
andfragment_course_runs_list
have been removed. If you have overridden those templates, you have now to override corresponding React widget (SyllabusCourseRunsList
). courses
app export new routes namedredirects_urlpatterns
. You have to add those new routes to the urls module of your app.from richie.apps.courses.urls import redirects_urlpatterns as courses_redirects_urlpatterns urlpatterns += [ re_path(r"^redirects/", include([*courses_redirects_urlpatterns])), ]
- Legacy colors are now defined in cunningham.cjs instead of palette.scss. You must import cunningham
scss tokens in your _main.scss files above the override of colors/palette.
// ... // Import Cunningham tokens and icons @import '@openfun/cunningham-react/dist/icons'; @import '@openfun/cunningham-react/dist/style'; @import 'richie-education/scss/vendors/cunningham-tokens'; @import 'richie-education/scss/vendors/css/cunningham-tokens'; // Override default Richie settings variables @import 'richie-education/scss/colors/palette'; // ...
yarn build-theme
command generates tokens filesscss/vendors/cunningham-tokens.scss
andscss/vendors/css/cunningham-tokens.css
.$palette
variable is now deprecated and will be removed in the next major release. Currently this is only an alias to themap.get($theme, colors)
($theme is a sass variable exported bycunninghtam-tokens.scss
). - Components
CourseGlimpse
andCourseGlimpseList
has been moved fromjs/widgets/Search
folder tojs/components
folder. Update your overrides.json and path in your custom scss files accordingly. js/utils/test/factories.ts
have been split into multiple files: joanie.ts, richie.ts and reactQuery.ts. Update your import accordingly.
- Frontend folder architecture has been totally reworked. If you have overridden any frontend components, you should have to update your overrides.json file to match new paths. In the same way, you should also check sass import paths in your custom scss files.
- The web analytics settings have been changed, from multiple settings to a single
WEB_ANALYTICS
dict setting. The dictkey
is the web analytics identification string and thevalue
is a dict with specific configuration for each web analytics solution. Nevertheless the sharedtracking_id
andlocation
keys are shared between all web analytics providers. If you extends the web analytics js code with your own solution, you should be careful, because the code has been changed to support multiple web analytics providers to be activated at the same time. For performance reasons the default location for the web analytics js code have been changed fromhead
tofooter
. So you should change theWEB_ANALYTICS
setting in your settings.py file:The old behavior can still be enabled if you use the next value on theWEB_ANALYTICS = values.DictValue( None, environ_name="WEB_ANALYTICS", environ_prefix=None, )
WEB_ANALYTICS
setting and replace theUA-TRACKING_ID
value with your own value of the removedWEB_ANALYTICS_ID
setting.{ 'google_universal_analytics': { 'tracking_id': 'UA-TRACKING_ID', 'location': 'head, }, }
- A new setting "FEATURES" has been added to enable some early features. If you want to test those
features you have to add this setting in your settings.py file:
# Feature flags FEATURES = values.DictValue(environ_name="FEATURES", environ_prefix=None)
-
In
_theme.scss
,course-detail
scheme now accepts two new optional properties to style the course run CTA and feedback color in the course detail subheader:subheader-run-cta
subheader-run-feedback-color
If those values are not set, the default values are respectively
run-cta
and `run-feedback-color properties.
- To manage Joanie's products and course runs, the settings
JOANIE_BACKEND
has to be bound intoRICHIE_LMS_BACKENDS
. To bind those settings add this code withinpost_setup
method ofBase
class configuration withinsettings.py
.@classmethod def post_setup(cls): ... # If a Joanie Backend has been configured, we add it into LMS_BACKENDS dict if cls.JOANIE_BACKEND.get("BASE_URL") is not None: cls.RICHIE_LMS_BACKENDS.append(cls.JOANIE_BACKEND)
- Richie is now able to delegate course enrollment to Joanie which will then synchronize its
course runs with Richie and provide advanced enrollment, ecommerce and multi-LMS features.
To set up this feature, you can add to
JOANIE_BACKEND
setting the following properties:JOANIE_BACKEND = { # ... "BACKEND": "richie.apps.courses.lms.joanie.JoanieBackend", "JS_BACKEND": "joanie", # The regex to match a resource that can be handle by the lms.joanie.JoanieBackend interface "COURSE_REGEX": r"^.*/api/v1.0/(?P<resource_type>(course-runs|products))/(?P<resource_id>[^/]*)/?$", # The regex to match a resource that can be handle by the lms.joanie.JoanieBackend interface "JS_COURSE_REGEX": r"^.*/api/v1.0/(course-runs|products)/([^/]*)/?$", # A list of course run properties to not update "COURSE_RUN_SYNC_NO_UPDATE_FIELDS": [], # The synchronization mode ("manual", "sync_to_public" or "sync_to_draft") "DEFAULT_COURSE_RUN_SYNC_MODE": "sync_to_public", }
- The way filters are configured has changed. There is now a separate setting
RICHIE_FILTERS_PRESENTATION
to easily define which filters are displayed and in which order. If you need to customize more than the list and order of the search filters, theRICHIE_FILTERS_CONFIGURATION
still exists and has a new simplified format.
- On frontend, the API interface
base
has been renamed intodummy
. <header>
,<nav>
and<footer>
DOM structure was updated for better accessibility. Make sure to check that everything still renders correctly if you override header or footer blocks in your templates.- The
_main.scss
file has been refactored, to made future upgrades more easy. The file_main.scss
can be more compact with lower probability of changes on future upgrades. Use the cookiecutter_main.scss
file as example. - RegisteredAddress now has a related stylesheet, you have to update the main stylesheet as follows:
_main.scss
+ @import 'richie-education/js/components/RegisteredAddress/styles';
- Only if you have overridden
_theme.scss
:
... +sale-tunnel: ( + primary-button-scheme: $firebrick6-scheme, + primary-button-is-outlined: false, + secondary-button-scheme: $purplish-grey-scheme, + secondary-button-is-outlined: true, + tertiary-button-scheme: $smoke-scheme, + tertiary-button-is-outlined: false, +), ...
-
New frontend widgets has been added, you have to update stylesheets as follows:
_main.scss
+ @import 'richie-education/scss/tools/utils'; + @import 'richie-education/js/components/AddressesManagement/styles'; + @import 'richie-education/js/components/CourseProductCertificateItem/styles'; + @import 'richie-education/js/components/CourseProductCourseRuns/styles'; + @import 'richie-education/js/components/CourseProductItem/styles'; + @import 'richie-education/js/components/PaymentButton/styles'; + @import 'richie-education/js/components/RegisteredCreditCard/styles'; + @import 'richie-education/js/components/SaleTunnel/styles'; + @import 'richie-education/js/components/SaleTunnelStepPayment/styles'; + @import 'richie-education/js/components/SaleTunnelStepResume/styles'; + @import 'richie-education/js/components/SaleTunnelStepValidation/styles'; + @import 'richie-education/js/components/StepBreadcrumb/styles'; ... + @import 'richie-education/scss/components/templates/richie/multiple-columns';
- Only if you have overridden
_palette.scss
:
$palette = { ... + 'mantis': #76ce68, }
- Only if you have overridden
_theme.scss
:
base-schemes: ( ... + active: $active-scheme, ) ... +product-item: ( + base-background: r-color('white'), + base-border: r-color('purplish-grey'), + light-color: r-color('white'), + base-color: r-color('charcoal'), + lighter-color: r-color('battleship-grey'), + button-color: r-color('white'), + button-background: r-color('firebrick6'), +), +registered-credit-card: ( + title-color: r-color('charcoal'), + base-color: r-color('purplish-grey'), +), ... +shadowed-box: ( + base-background: r-color('white'), + base-shadow: 0 2px 4px rgba(5, 18, 42, 0.19), +), ... +steps-breadcrumb: ( + icon-background-active: r-color(purplish-grey), + icon-background: transparent, + icon-border-active: transparent, + icon-border: r-color('light-grey'), + icon-fill-active: r-color('white'), + icon-fill: r-color('light-grey'), + icon-outline: rgba(r-color(purplish-grey), 0.25), + label-color-active: r-color('charcoal'), + label-color: r-color('light-grey'), + separator-background-active: rgba(r-color(purplish-grey), 0.6), + separator-background: rgba(r-color(purplish-grey), 0.25), +), +steps-content: ( + content-color: r-color(purplish-grey), + icon-background: r-color(indianred3), + icon-color: r-color('white'), + icon-big-background: transparent, + icon-big-color: r-color('charcoal'), + icon-success-background: r-color('mantis'), + icon-success-color: r-color('white'), + title-color: r-color('charcoal'), + subtitle-color: r-color(purplish-grey), +)
-
The
get_placeholder_plugins
andget_page_plugins
template tags were merged in a single placeholderget_placeholder_plugins
by making thepage_lookup
parameter optional. A new template tagplaceholder_as_plugins
was introduced and should be used in place of theget_placeholder_plugins
tag wherever you want a real placeholder (with markup for frontend editing) and not just getting the related plugins. -
Don't use the
. They can be replaced by a simple {% if %} tag since their only purpose is to inject markup for frontend editing (which is not valid html in the page header).blockplugin
template tag in the page -
The
runs_open
django template block have been replaced byrun_open_single
andruns_open_multiple
blocks on thecourse_detail.html
template. -
The
contact
block has been removed from thecourse_detail.html
template, if you overwrite it please consider the newrun_open_single
block as alternative. -
Frontend override system has been updated to allow overriding of any frontend module. Thus if you override some components, you have to update the module regexp by prefixing with
components/
.- "CourseGlimpse/CourseGlimpseFooter.tsx": "../../../../../js/components/CourseGlimpse/CourseGlimpseFooter.tsx" + "components/CourseGlimpse/CourseGlimpseFooter.tsx$": "../../../../../js/components/CourseGlimpse/CourseGlimpseFooter.tsx"
-
If you customize the
course-detail
block theme add thecheckmark-list-decoration-color
variable.
- Add
dal
anddal_select2
to your installed apps.INSTALLED_APPS = ( # ... 'dal', 'dal_select2', )
- If you overrode
course-detail
theme withintheme.scss
, you have to add these four new propertiesview-more-runs-color: r-color('firebrick6'), run-catalog-visibility-hidden-logo: url('../../richie/images/catalog_visibility/hidden.svg'), run-catalog-visibility-course-only-logo: url('../../richie/images/catalog_visibility/course_only.svg'), run-catalog-visibility-logo-color: r-color('indianred3'),
- If you overrode
richie/base.html
, thebranding_footer
template block has been renamed tobody_footer_brand
and the link was integrated in the block so it can be customized. - The file
_colors.scss
has been divided into_palette.scss
for the palette,_gradients.scss
,_schemes.scss
and_theme.scss
. Those files are now located in a dedicated foldercolors
.
-
Add easing timing function variables to
settings/_variables.scss
:// Easings (Quart) $r-ease-in: cubic-bezier(0.5, 0, 0.75, 0); $r-ease-out: cubic-bezier(0.25, 1, 0.5, 1); $r-ease-in-out: cubic-bezier(0.76, 0, 0.24, 1);
-
Define the
form
scheme withinsettings/_colors.scss
and import the new CSS file related to forms in_main.scss
:@import 'richie-education/scss/objects/form';
-
Add to
spinner
scheme propertybase-color-light
-
Import the new CSS file related to modal in
_main.scss
:@import 'richie-education/js/components/Modal/styles';
These new styles also require modifications to variables in
settings/_colors.scss
. To keep the existing behaviors unchanged:- create a new
modal
entry at the same level assearch-filters-group-modal
; - move
base-background
,base-border
,base-color
andoverlay-background
fromsearch-filters-group-modal
tomodal
; - copy
close-background
,close-border
andclose-color
fromsearch-filters-group-modal
tomodal
; - delete
modal-overlay-background
fromsearch-filters-group
.
Here is a code example of valid values for these entries:
search-filters-group: ( title-color: r-color('battleship-grey'), ), modal: ( base-background: r-color('white'), base-border: r-color('battleship-grey'), base-color: r-color('battleship-grey'), close-background: r-color('white'), close-border: r-color('silver'), close-color: r-color('black'), overlay-background: r-color('white'), ), search-filters-group-modal: ( button-background: r-color('white'), button-color: r-color('dark-aquamarine'), close-background: r-color('white'), close-border: r-color('silver'), close-color: r-color('black'), input-background: r-color('silver'), input-color: r-color('black'), item-border: r-color('silver'), ),
- create a new
- Add
django.contrib.humanize
to your installed apps.INSTALLED_APPS = ( # ... 'django.contrib.humanize', )
- If you want to activate the new feature showing the enrollment count on the course detail page,
set the
RICHIE_MINIMUM_COURSE_RUNS_ENROLLMENT_COUNT
setting to a value greater than 0, to specify the minimum number of enrollments for a course (accross all its sessions) starting from which you want to show the enrollment count. It will display as: "1000 already enrolled!"
.no-scheme-fill
css class util has been removed.IndexableMPTTFilterDefinition
class was renamed toIndexableHierarchicalFilterDefinition
. If your project defines custom filter definitions in theRICHIE_FILTERS_CONFIGURATION
setting, you need to make sure you don't point to the old class name.- A new scss variable has been added
$r-course-subheader-aside
. If you have overridden_variables.scss
file, you have to define this variable. - Add a new entry to your
urls.py
declarations for therobot.txt
file so that thesitemap.xml
file is found without the need to register it in each crawler administration panel:path( "robots.txt", TemplateView.as_view( template_name="richie/robots.html", content_type="text/plain" ), )
- Named capturing group regex are still considered experimental in Javascript and may cause trouble
with old browsers, so we decided to remove this feature from Richie and use indexed capturing
group instead. As a consequence, you should update your
JS_COURSE_REGEX
setting to remove thecourse_id
named group. - Frontend JS is now generated into a dedicated
build
folder insidestatic/js
. So if you need these scripts in templates, you have to update the script tag src to new destination.static/js/index.js
becomesstatic/js/build/index.js
- An API endpoint has been created to retrieve the context of a LTI Consumer plugin.
You need to append this route to api routes in your
urls
configuration. Furthermore to optimize db accesses, if a cache calledmemory_cache
is defined inCACHES
, the response will be cached for 9min 30s.
- A new
COURSE_RUN_SYNC_NO_UPDATE_FIELDS
setting has been added toRICHIE_LMS_BACKENDS
. These fields will not be updated by the course run synchronization hook. - A css
.banner
component has been created. You need to import the component styleobjects/_banner.scss
into your main stylesheet to be able to use it. - A css LtiConsumer component has been created for the new LTI consumer plugin. You need to
import the component style
../js/components/LtiConsumer/styles
into your main stylesheet so the LTI consumer plugin renders as expected.
RICHIE_AUTHENTICATION_DELEGATION["PROFILE_URLS"]
setting is now a dictionary : a key has been added to each url, permitting to get one easily.- Richie has now its own error templates. You can use them by setting
handler400
,handler403
,handler404
andhandler500
to its related view (richie.apps.core.views.error.error_<ERROR_CODE>_view_handler
).- In your project's
urls.py
, add these lines at the end of the file:... + handler400 = "richie.apps.core.views.error.error_400_view_handler" + handler403 = "richie.apps.core.views.error.error_403_view_handler" + handler404 = "richie.apps.core.views.error.error_404_view_handler" + handler500 = "richie.apps.core.views.error.error_500_view_handler"
- In your project's
- Richie version 2 introduces a new
AUTHENTICATION_BACKEND
setting used to get session information from OpenEdX through CORS requests. So login, register and logout routes are constructed from the BASE_URL of this setting. Furthermore it takes an extra propertyPROFILE_URLS
. This property is consumed by UserLogin react component to display links that should redirect user on backend authentication account views (e.g: Profile, Dashboard, Settings). - Richie version 2 is a major overhaul of all the project's templates and css files to bring
a complete new design. If you were overriding the old templates and css base, you have 2
options:
- copy the old templates and css files to your project and start maintaining them on your own,
- refactor your project to accomodate the new design.
- Section plugin template "section_cadenced" has been removed since it was covering special
case from old layout integration. A migration has been added to automatically update Section
plugins which used it to use the default one instead (the first from
SECTION_TEMPLATES
choices). You may have to upgrade your settings if you were overriding it throughRICHIE_SECTION_TEMPLATES
. - Section plugin template "section_list" has been removed since it was covering special case
for footer menu which is now intended to be done with new
NestedItem
. A migration has been added to automatically update Section plugins which used it to use the default one instead (the first fromSECTION_TEMPLATES
choices). You may have to upgrade your settings if you were overriding it throughRICHIE_SECTION_TEMPLATES
. Also we recommend you to rebuild your footer menu withNestedItem
instead ofSection
plugins. - Course plugin variant choices has been updated. Previously "small" variant existed but do nothing, now this variant apply same styles than default variant to prevent layout issue. Furthermore a "large" variant has been added which display larger course glimpse.
- The template tags related to placeholders were refactored to fix ghost placeholders. This
change impacts the use of template tags in all templates:
- The
fragment_course_content.html
template is removed and its content is inserted directly in thecourse_detail.html
andcourse_run_detail.html
templates, using theplaceholder
template tag for the former and theshow_placeholder
template tag for the latter; - The
get_page_placeholder
template tag is removed and replaced either byplaceholder
when it is used on its own page andshow_placeholder
when it is used on another page; - The
get_placeholder_plugins
template tag is replaced by a newget_page_plugins
template tag when it is used on another page than the placeholder's own page.
- The
- This release changes names for ElasticSearch indices. Unless they explicitly use
RICHIE_ES_INDICES_PREFIX
setting to replicate the previous behavior (by setting it to"richie"
), all users will have to regenerate all ElasticSearch indices (can be done by running thebootstrap_elasticsearch
command).
- If you override the
courses/cms/blogpost_list.html
template and want to benefit from the display of news-related categories on top of the page, you need to add the new markup and css. - All occurences of the
form_factor
variable have been renamed tovariant
for clarity. Search and replace throughout your template overrides. - The
courses/cms/fragment_category_glimpse.html
andcourses/plugins/category_plugin.html
templates were refactored for a better modularity and harmonization with other types of pages. You must port these modifications to your project if you override either of these two templates. - Users who make use of
<SearchSuggestField />
or<RootSearchSuggestField />
in their own templates throughrichie-react
need to update all the call sites: thecontext
prop is now required for both of them. See the documentation for more details oncontext
.
- If you override the
courses/cms/blogpost_list.html
and/orcourses/cms/blogpost_detail.html
templates, you need to port the modifications made to display thepublication_date
instead of thecreation date
and to hide blog posts that are not in the publication window from the public site. - Users who changed the
search.html
template need to update it to include the page title and search bar themselves. They need to add a<h1>
where they wish on the page, and the<SearchSuggestField />
component through the django-react interop somewhere on the page too.
- If you reused any React components in Django templates through
richie-react
, you should know that thedata-locale
attribute on them is no longer used. Instead, they rely on<html lang>
to pick up their current locale, which should already be set in all documents anyway. - As a result, the
lang
attribute on<html>
, which is a requirement for an accessible page anyway, is now an absolute requirement. Users who overrode the base template and removed this need to add it again. - Users who overrode the
REACT_LOCALES
setting need to rename it toRFC_5646_LOCALES
and make sure it contains BCP47/RFC5646 locales (REACT_LOCALES
used ISO15897 locales). - Footer links are now defined via a static placeholder (see CHANGELOG). Richie provides a data migration to make sure that an existing footer of flat links is ported to the new static placeholder. Before running the data migration, make sure all changes on the footer pages (pages that are below the page with a reverse_id of "annex") are published. After running the data migration, check the footer (draft and public in each language) to make sure it is as expected.
- A login/signup component was added at the top right of all pages. It comes with new url routes
that you must add to your project:
- In your project's
urls.py
non-i18n patterns, add user-related API endpoints via richie's core app urls:... + from richie.apps.core.urls import urlpatterns as core_urlpatterns ... urlpatterns = [ ... - url(r"^api/{}/".format(API_PREFIX), include(search_urlpatterns)), + url( + r"^api/{}/".format(API_PREFIX), + include([*core_urlpatterns, *search_urlpatterns]), + ), ... ]
- In your project's
urls.py
i18n patterns, add Django contrib auths urls:urlpatterns += i18n_patterns( ... + url(r"^accounts/", include("django.contrib.auth.urls")), ... )
- In your project's settings, configure login and logout redirect urls:
... + LOGIN_REDIRECT_URL = "/" + LOGOUT_REDIRECT_URL = "/"
- In your project's
- If you override the
menu/language_menu.html
template, you should now include the<ul>
tag in this template and not inrichie/base.html
so that it does not render as an empty element on sites with only one public language, - If you override templates that contain React hooks, rename the
fun-react
class torichie-react
.
If you override _course_detail.scss
, the course-detail__aside__run
selector was renamed
to course-detail__aside__runs
in our course_detail.html
template.
No specific actions are required for this release.
- Icon font has been removed and replaced with SVG icons. Any overridden template(s) using icons from the icon font need to be updated to use SVG icons too.
- For each item in the changelog, check that your css overrides have no impact.
A new third party application was added to enable pagination on blogposts and persons list. You must update your settings as follows:
- Add
dj-pagination
to your installed apps:INSTALLED_APPS = ( # ... 'dj_pagination', )
- Add the pagination middleware to your settings:
MIDDLEWARE = ( # ... 'dj_pagination.middleware.PaginationMiddleware', )
- Add pagination options to your settings as per your requirements. See https://dj-pagination.readthedocs.io/en/latest/usage.html#optional-settings for a list of all available settings.