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-cardtheme 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')
),
CourseProductItemhas been moved intoSyllabusCourseRunsList/componentsfolder. If you have overridden this component, you have to update your overrides.json file accordingly.JOANIE_BACKENDmust be updated.COURSE_REGEXandJS_COURSE_REGEXmust 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.scssfile. You have to import it in your_main.scssfile.// ... // Import bootstrap reset @import 'richie-education/scss/trumps/bootstrap';
- Delete richie Button component now that we use cunningham Button component.
*_detail.htmldjango 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-contentmap 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_runandfragment_course_runs_listhave been removed. If you have overridden those templates, you have now to override corresponding React widget (SyllabusCourseRunsList). coursesapp 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-themecommand generates tokens filesscss/vendors/cunningham-tokens.scssandscss/vendors/css/cunningham-tokens.css.$palettevariable 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
CourseGlimpseandCourseGlimpseListhas been moved fromjs/widgets/Searchfolder tojs/componentsfolder. Update your overrides.json and path in your custom scss files accordingly. js/utils/test/factories.tshave 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_ANALYTICSdict setting. The dictkeyis the web analytics identification string and thevalueis a dict with specific configuration for each web analytics solution. Nevertheless the sharedtracking_idandlocationkeys 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 fromheadtofooter. So you should change theWEB_ANALYTICSsetting 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_ANALYTICSsetting and replace theUA-TRACKING_IDvalue with your own value of the removedWEB_ANALYTICS_IDsetting.{ '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-detailscheme now accepts two new optional properties to style the course run CTA and feedback color in the course detail subheader:subheader-run-ctasubheader-run-feedback-color
If those values are not set, the default values are respectively
run-ctaand `run-feedback-color properties.
- To manage Joanie's products and course runs, the settings
JOANIE_BACKENDhas to be bound intoRICHIE_LMS_BACKENDS. To bind those settings add this code withinpost_setupmethod ofBaseclass 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_BACKENDsetting 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_PRESENTATIONto 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_CONFIGURATIONstill exists and has a new simplified format.
- On frontend, the API interface
basehas 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.scssfile has been refactored, to made future upgrades more easy. The file_main.scsscan be more compact with lower probability of changes on future upgrades. Use the cookiecutter_main.scssfile 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_pluginsandget_page_pluginstemplate tags were merged in a single placeholderget_placeholder_pluginsby making thepage_lookupparameter optional. A new template tagplaceholder_as_pluginswas introduced and should be used in place of theget_placeholder_pluginstag 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).blockplugintemplate tag in the page -
The
runs_opendjango template block have been replaced byrun_open_singleandruns_open_multipleblocks on thecourse_detail.htmltemplate. -
The
contactblock has been removed from thecourse_detail.htmltemplate, if you overwrite it please consider the newrun_open_singleblock 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-detailblock theme add thecheckmark-list-decoration-colorvariable.
- Add
dalanddal_select2to your installed apps.INSTALLED_APPS = ( # ... 'dal', 'dal_select2', )
- If you overrode
course-detailtheme 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_footertemplate block has been renamed tobody_footer_brandand the link was integrated in the block so it can be customized. - The file
_colors.scsshas been divided into_palette.scssfor the palette,_gradients.scss,_schemes.scssand_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
formscheme withinsettings/_colors.scssand import the new CSS file related to forms in_main.scss:@import 'richie-education/scss/objects/form';
-
Add to
spinnerscheme 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
modalentry at the same level assearch-filters-group-modal; - move
base-background,base-border,base-colorandoverlay-backgroundfromsearch-filters-group-modaltomodal; - copy
close-background,close-borderandclose-colorfromsearch-filters-group-modaltomodal; - delete
modal-overlay-backgroundfromsearch-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.humanizeto 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_COUNTsetting 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-fillcss class util has been removed.IndexableMPTTFilterDefinitionclass was renamed toIndexableHierarchicalFilterDefinition. If your project defines custom filter definitions in theRICHIE_FILTERS_CONFIGURATIONsetting, 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.scssfile, you have to define this variable. - Add a new entry to your
urls.pydeclarations for therobot.txtfile so that thesitemap.xmlfile 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_REGEXsetting to remove thecourse_idnamed group. - Frontend JS is now generated into a dedicated
buildfolder insidestatic/js. So if you need these scripts in templates, you have to update the script tag src to new destination.static/js/index.jsbecomesstatic/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
urlsconfiguration. Furthermore to optimize db accesses, if a cache calledmemory_cacheis defined inCACHES, the response will be cached for 9min 30s.
- A new
COURSE_RUN_SYNC_NO_UPDATE_FIELDSsetting has been added toRICHIE_LMS_BACKENDS. These fields will not be updated by the course run synchronization hook. - A css
.bannercomponent has been created. You need to import the component styleobjects/_banner.scssinto 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/stylesinto 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,handler404andhandler500to 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_BACKENDsetting 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_TEMPLATESchoices). 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_TEMPLATESchoices). You may have to upgrade your settings if you were overriding it throughRICHIE_SECTION_TEMPLATES. Also we recommend you to rebuild your footer menu withNestedIteminstead ofSectionplugins. - 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.htmltemplate is removed and its content is inserted directly in thecourse_detail.htmlandcourse_run_detail.htmltemplates, using theplaceholdertemplate tag for the former and theshow_placeholdertemplate tag for the latter; - The
get_page_placeholdertemplate tag is removed and replaced either byplaceholderwhen it is used on its own page andshow_placeholderwhen it is used on another page; - The
get_placeholder_pluginstemplate tag is replaced by a newget_page_pluginstemplate 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_PREFIXsetting 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_elasticsearchcommand).
- If you override the
courses/cms/blogpost_list.htmltemplate 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_factorvariable have been renamed tovariantfor clarity. Search and replace throughout your template overrides. - The
courses/cms/fragment_category_glimpse.htmlandcourses/plugins/category_plugin.htmltemplates 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-reactneed to update all the call sites: thecontextprop is now required for both of them. See the documentation for more details oncontext.
- If you override the
courses/cms/blogpost_list.htmland/orcourses/cms/blogpost_detail.htmltemplates, you need to port the modifications made to display thepublication_dateinstead of thecreation dateand to hide blog posts that are not in the publication window from the public site. - Users who changed the
search.htmltemplate 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-localeattribute 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
langattribute 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_LOCALESsetting need to rename it toRFC_5646_LOCALESand make sure it contains BCP47/RFC5646 locales (REACT_LOCALESused 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.pynon-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.pyi18n 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.htmltemplate, you should now include the<ul>tag in this template and not inrichie/base.htmlso 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-reactclass 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-paginationto 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.