OEP-16: Bootstrap Adoption #46
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,195 @@ | ||
| ========================== | ||
| OEP-16: Bootstrap Adoption | ||
| ========================== | ||
|
|
||
| +---------------+-------------------------------------------+ | ||
| | OEP | :doc:`OEP-16 </oeps/oep-0016>` | | ||
| +---------------+-------------------------------------------+ | ||
| | Title | Bootstrap Adoption | | ||
| +---------------+-------------------------------------------+ | ||
| | Last Modified | 2017-04-21 | | ||
| +---------------+-------------------------------------------+ | ||
| | Author | Andy Armstrong <[email protected]> | | ||
| +---------------+-------------------------------------------+ | ||
| | Arbiter | _TBD_ | | ||
| +---------------+-------------------------------------------+ | ||
| | Status | Draft | | ||
| +---------------+-------------------------------------------+ | ||
| | Type | Architecture | | ||
| +---------------+-------------------------------------------+ | ||
| | Created | 2017-04-18 | | ||
| +---------------+-------------------------------------------+ | ||
|
|
||
| Abstract | ||
| ======== | ||
|
|
||
| In order to accelerate development, and provide a more consistent user | ||
| experience for our users, edX will adopt Bootstrap 4 to build all of its web | ||
| applications. The Open edX 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 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`_. | ||
|
|
||
| Technology Selection | ||
| ==================== | ||
|
|
||
| The following rubric was used to assess potential technologies: | ||
|
|
||
| * Learning curve / prior experience | ||
| * Options for community - force them down a path or give them options | ||
| * Frameworks that are opinionated vs. flexible | ||
| * Ability to easily build accessible front-ends | ||
| * Ease of design-framework integration | ||
|
There was a problem hiding this comment. Nit: "design-framework" is confusing upon initial read. Perhaps just, "Ease of integration". |
||
| * DIY framework vs. all-inclusive platform | ||
| * Willingness to dedicate resources to development and maintenance | ||
| * Ease of prototyping | ||
| * Community project support | ||
| * Compliance and security considerations | ||
| * Availability of developers (hiring ability) | ||
| * Ability to achieve business strategy | ||
|
|
||
| In addition, there were a number of key goals that such a technology must | ||
| address: | ||
|
|
||
| * accessibility | ||
| * internationalization and right-to-left languages | ||
| * theming | ||
| * performance | ||
| * mobile-first responsive designs | ||
|
There was a problem hiding this comment. "Mobile-first" and "responsive" to me are two different things. I don't know which one we're adopting but we should clarify this terminology, as they have different goals and outcomes. |
||
| * extensibility / ease of overriding | ||
| * modularity / scoping | ||
| * Open edX community interest | ||
| * size and activity of the framework's community? | ||
|
There was a problem hiding this comment. Is the "?" here to indicate this goal might be cut? It seems to be by the rubric item, "Community project support." |
||
| * integration with build systems | ||
| * integration into existing edX pages | ||
|
|
||
| Bootstrap is the industry standard web framework with a comprehensive collection | ||
|
There was a problem hiding this comment.
Would "design framework" be a better term for it? "Web framework" to me makes me think of Django, Rails, etc. |
||
| of web components. Each of these components is designed to be mobile-first, | ||
| meaning that Bootstrap applications look good at phone, tablet, and desktop | ||
| sizes. | ||
|
There was a problem hiding this comment.
Back to my comment above - this to me is a description of "responsive." "Mobile-first", in my mind, signifies that it's designed with handsets as the primary use case and scales to work on desktop but desktop remains a secondary use case. Examples: The Boston Globe is responsive, because everything works generally equally well across all platforms. Facebook is mobile-first because everything important happens in a core content area of ~500px and the layout doesn't really make full use of the full desktop real estate. Some features only work on mobile and it's clear that the interaction model (the same one you get regardless of the platform you view FB on) is designed with touch input and small screens in mind. There was a problem hiding this comment. @bjacobel -- agree on the mobile-first comment. It's about the implementing for the primary use case and thinking of all other cases are exceptions. |
||
|
|
||
| Bootstrap 4 is the first version to support key requirements for adoption | ||
| within the edX platform: | ||
|
|
||
| * Bootstrap 4 has switched to using Sass (previous versions used Less) | ||
| * It provides a more flexible grid system that supports all of edX's layouts | ||
|
There was a problem hiding this comment. Do you mean the introduction of flex box utilities? The grid system hasn't changed much as far as I can tell. There was a problem hiding this comment. I was thinking of the combination of flexbox plus the improvements they describe here: https://blog.getbootstrap.com/2015/08/19/bootstrap-4-alpha/
|
||
| * It uses ems and rems for responsive typography | ||
|
|
||
| Another key factor in the switch is the wide availability of Boostrap-based | ||
|
There was a problem hiding this comment. There is just reactstrap, as far as I know. |
||
| 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 a proprietary markup scheme. XBlock authors | ||
|
There was a problem hiding this comment. I'm guessing this refers to the custom HTML needed, for example, to render custom components in the Pattern Library. |
||
| and platform developers alike can target the standard Bootstrap markup which | ||
| is very well documented. This saves time in development, and also ensures that | ||
| the new user interface will be rendered according to the current theme. | ||
|
|
||
| Specification | ||
| ============= | ||
|
|
||
| The recommendation is to adopt Bootstrap 4 starting immediately so that new | ||
| features can be built following this best practice. In edX platform, the core | ||
| templates will be parameterized to support the option of using Bootstrap. With | ||
| this option chosen, the page skeleton (header, footer, navigation) will | ||
| automatically render in a mobile-first design using Bootstrap components. | ||
|
|
||
| New Bootstrap themes will be implemented in the `edX UI Toolkit`_. These themes | ||
| will be provided as Sass partial files that can be included into any project's | ||
| Sass file. The files will be as follows: | ||
| * A partial defining the standard edX fonts, layouts, margins etc | ||
|
There was a problem hiding this comment. Add a new line before this one so the RST renders properly. |
||
| * An edx.org brand partial which defines the edX colors and background images | ||
| * An Open edX partial that defines the community colors and images | ||
|
|
||
| An Open edX site can 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. | ||
|
|
||
| One important consideration is that as of April 2017, Bootstrap 4 is still | ||
| in alpha. 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. | ||
|
|
||
| Backward Compatibility | ||
| ====================== | ||
|
|
||
| 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 | ||
|
There was a problem hiding this comment. What about "global" components like the header and footer? There was a problem hiding this comment. The approach I took in the reference implementation was to conditionalize the header and footer templates with a "use_bootstrap" context parameter. If Bootstrap is being used, the template outputs Bootstrap components. I'll add this explanation. |
||
| 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. | ||
|
|
||
| Reference Implementation | ||
| ======================== | ||
|
|
||
| In order to prove the viability of Bootstrap 4, a proof-of-concept was built | ||
| that converted three different pages from the LMS: | ||
|
|
||
| * The course bookmarks page which was a simple first page to target | ||
| * The main courseware page which contains a number of custom styling rules | ||
| * The new course outline page which is a typical `edX Pattern Library`_ page | ||
|
|
||
| The following work was done: | ||
|
|
||
| * A new lms-main-v3.scss file was introduced that used Bootstrap | ||
| * An edX Bootstrap theme was implemented and included as a partial | ||
| * The three pages were switched over to use the v3 styling | ||
| * A "uses_bootstrap" context parameter enables a template to add Bootstrap JS | ||
| * The header was reimagined with Bootstrap components | ||
| * The page styles were updated to use Bootstrap mixins and theme variables | ||
|
|
||
| For the courseware, a new lms-course-v3.scss was added | ||
|
|
||
| * This file included all of the course-specific Sass partials | ||
| * Any global-level rules were excluded to allow Bootstrap's styles to be used | ||
|
|
||
| See the `Bootstrap Proof-of-Concept PR`_ for more details, including screenshots | ||
|
There was a problem hiding this comment. We should also do a proof-of-concept for theming for both single and multi-tenancy. Theming for a single tenant is relatively easy, but not so much for multiple tenants as evidenced by the fact that we still haven't settled on a single method of theming: There was a problem hiding this comment. I'd love to talk to you more about theming, as I'm only familiar with comprehensive theming in edX platform. For that, there is already a separate Sass file per site, so I was thinking that each file would just include its own Bootstrap theme partial. Let's get together with @douglashall, @gsong, and other interested theming folks to come up with a consistent approach. |
||
| 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. | ||
|
|
||
| Rejected Alternatives | ||
| ===================== | ||
|
|
||
| edX Pattern Library | ||
| ------------------- | ||
|
|
||
| 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 an entire web framework, 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`_. | ||
|
|
||
| Material Design | ||
| --------------- | ||
|
|
||
| Google's Material Design is another very successful web framework that was | ||
| evaluated. It was ultimately considered to be too opinionated to support the | ||
|
There was a problem hiding this comment. I don't remember when this conclusion was drawn. And I personally think Material design was conceived for a wide variety of use cases for material design, specifically Material Components are also kept up to date by Google. |
||
| variety of sites in the Open edX community. | ||
|
|
||
| .. _Bootstrap: http://getbootstrap.com/ | ||
| .. _Bootstrap Proof-of-Concept PR: https://github.com/edx/edx-platform/pull/14834 | ||
| .. _edX accessibility guidelines: http://edx.readthedocs.io/projects/edx-developer-guide/en/latest/conventions/accessibility.html | ||
| .. _edX Front End Working Group: https://openedx.atlassian.net/wiki/display/FEDX/Front+End+Working+Group | ||
| .. _edX UI Toolkit: http://ui-toolkit.edx.org/ | ||
| .. _OEP-11 - Front End Technology Standards: http://open-edx-proposals.readthedocs.io/en/latest/oep-0011.html | ||
| .. _edX Pattern Library: http://ux.edx.org/ | ||
| .. _State of the Pattern Library: https://openedx.atlassian.net/wiki/display/FEDX/State+of+the+Pattern+Library | ||
| .. _WCAG 2.0: http://www.w3.org/TR/WCAG20/ | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"style" or "theme" might be a more appropriate word here? Nitty semantics but it's also the thesis of the OEP so I want to make sure it's clear.