OEP | OEP-16 |
Title | Bootstrap Adoption |
Last Modified | 2017-06-19 |
Author | Andy Armstrong <andya@edx.org> |
Arbiter | Dennis Jen <djen@edx.org> |
Status | Accepted |
Type | Architecture |
Created | 2017-04-18 |
Resolution | Original pull request |
In order to accelerate development, and provide a more consistent user experience for our users, Open edX will adopt Bootstrap 4 to style its web applications. The community will be able to extend the platform using any of Bootstrap’s collection of components, as well as use Bootstrap theming to brand their instances. An Open edX-supported subset of components will be provided that are verified to support WCAG 2.0 to ensure that all new user interfaces conform to the edX accessibility guidelines.
The following rubric was used to assess potential technologies:
In addition, there were a number of key goals that such a framework must address:
Bootstrap is the leading framework for designing web applications. It comes with a comprehensive collection of components that are designed to be responsive, meaning that Bootstrap applications look good at phone, tablet, and desktop sizes.
Bootstrap 4 is the first version to support key requirements for adoption within the edX platform:
Another key factor in the switch is the availability of Bootstrap-based React components. With edX’s move to adopt React (see OEP-11 - Front End Technology Standards), this will provide the community with an ever increasing set of components with which to extend the platform.
Finally, a critical benefit to using Bootstrap is that the edX community does not need to build or work with proprietary HTML classes. XBlock authors and platform developers alike can target the standard Bootstrap classes which are very well documented. This saves time in development, and also ensures that the new user interface will be rendered according to the current theme.
The recommendation is to adopt Bootstrap 4 starting immediately so that new features can be built following this best practice. A new edx-bootstrap library will be provided for installation via npm into any Open edX application. The library will include implementations of Bootstrap themes for Open edX and edx.org. Bootstrap themes are implemented as Sass partial files that define values for all the customizable variables such as fonts, layouts, colors, margins etc.
The current recommendation is that the library provide the following partials:
An Open edX site can then provide its own brand colors and images while still importing the standard fonts, layouts, margins etc. If desired, even those rules can be overridden to provide full flexibility in theming.
As of May 2017, Bootstrap 4 is still only available as an alpha release. Based upon the proof-of-concept, this does not seem to be an issue as the functionality is very complete, and the beta release is imminent. As this is an open source project, it is straightforward to track the work, and to provide fixes as necessary.
Bootstrap 4 does not currently provide support for right-to-left languages, which is clearly a roadblock for Open edX to adopt it. The official stance from Bootstrap is that this support will be added in a minor release after Bootstrap 4.0 is released. Given this, a solution needs to be found if Open edX is to adopt Bootstrap earlier.
There were two primary options considered:
The Open edX Front End Working Group discussed both options and decided that there are several benefits of rtlcss over bi-app-sass:
Given this decision, the reference implementation (see below) was updated to use rtlcss. This proof-of-concept successfully demonstrated pages rendered right-to-left which confirmed the choice.
Note: once Bootstrap chooses its own approach, it will be necessary to revisit this decision. It might be simpler, for example, to switch to use the same technology for simplicity’s sake.
For more background, see the Bootstrap RTL Discovery ticket.
A key question for Bootstrap adoption is how to implement theming for an application that supports multi-tenancy. Full theming encompasses many dimensions such as CSS, images, templates, and even feature configuration. For the purposes of an Open edX Bootstrap implementation, a solution needs to compile new versions of each application CSS file that includes the tenant’s Bootstrap theme partial file. The application must then return the tenant’s version of each CSS file when rendered.
The technical approach for multi-tenancy is out-of-scope of this OEP, but it is important that the edx-bootstrap library take this requirement into account.
For edx-platform, the approach taken in the reference implementation was to introduce a new v3 style, thus leaving all v1 and v2 styles unaffected. This allows pages to be converted one at a time.
An investigation was performed to see whether Bootstrap components could be used on non-Bootstrap pages, but the conclusion was that the conflicts made this more trouble than it was worth. The recommendation is to convert pages in one shot which will be quicker and will have fewer issues. For shared templates such as the header or footer, a context parameter will be passed through indicating whether Bootstrap components should be used.
In order to prove the viability of Bootstrap 4, a proof-of-concept was built that converted three different pages from the LMS:
The following work was done:
For the courseware, a new lms-course-v3.scss was added
See the Bootstrap Proof-of-Concept PR for more details, including screenshots of the three converted pages. Note: the proof-of-concept was mostly completed during a two-day hackathon, thus demonstrating how quickly these conversions can be done.
The edX Pattern Library is an initiative that was started in 2015 to modernize the way that edX applications were built. At the time, Bootstrap was considered to not be suitable for edX because applications always looked like they were built with Bootstrap. In addition, Bootstrap’s rules were defined using Less and so were not compatible with edX’s Sass-based styles. Finally, all sizing was done using pixels which was not compatible with responsive typography.
The pattern library project was somewhat successful, and a number of edX pages were built using it. However, it became clear that there were not enough resources available to build a comprehensive solution, and the non-standard nature of the project meant that the community chose not to adopt it. It was at this point that the edX Front End Working Group decided to investigate other alternatives.
For more information, see the wiki page State of the Pattern Library.
Google’s Material Design is another very successful web framework that was evaluated. It was ultimately considered to be too opinionated to support the variety of sites in the Open edX community.