From 1fb54d1491fea382521bdec717d1e28f20c3a1cf Mon Sep 17 00:00:00 2001 From: Andy Armstrong Date: Tue, 18 Apr 2017 18:06:59 -0400 Subject: [PATCH 1/4] First draft of OEP-16: Bootstrap Adoption --- oeps/oep-0016.rst | 195 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 oeps/oep-0016.rst diff --git a/oeps/oep-0016.rst b/oeps/oep-0016.rst new file mode 100644 index 000000000..bf8cc24df --- /dev/null +++ b/oeps/oep-0016.rst @@ -0,0 +1,195 @@ +========================== +OEP-16: Bootstrap Adoption +========================== + ++---------------+-------------------------------------------+ +| OEP | :doc:`OEP-16 ` | ++---------------+-------------------------------------------+ +| Title | Bootstrap Adoption | ++---------------+-------------------------------------------+ +| Last Modified | 2017-04-21 | ++---------------+-------------------------------------------+ +| Author | Andy Armstrong | ++---------------+-------------------------------------------+ +| 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 +* 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 +* extensibility / ease of overriding +* modularity / scoping +* Open edX community interest +* size and activity of the framework's community? +* integration with build systems +* integration into existing edX pages + +Bootstrap is the industry standard web framework with a comprehensive collection +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. + +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 +* It uses ems and rems for responsive typography + +Another key factor in the switch is the wide availability of Boostrap-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 a proprietary markup scheme. XBlock authors +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 +* 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 +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 +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 +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/ From f1f02d833644d20767d5c58db06673e8e34252c4 Mon Sep 17 00:00:00 2001 From: Andy Armstrong Date: Wed, 17 May 2017 13:40:31 -0400 Subject: [PATCH 2/4] Second draft addressing feedback --- oeps/oep-0016.rst | 140 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 103 insertions(+), 37 deletions(-) diff --git a/oeps/oep-0016.rst b/oeps/oep-0016.rst index bf8cc24df..5865bd147 100644 --- a/oeps/oep-0016.rst +++ b/oeps/oep-0016.rst @@ -7,11 +7,11 @@ OEP-16: Bootstrap Adoption +---------------+-------------------------------------------+ | Title | Bootstrap Adoption | +---------------+-------------------------------------------+ -| Last Modified | 2017-04-21 | +| Last Modified | 2017-05-17 | +---------------+-------------------------------------------+ | Author | Andy Armstrong | +---------------+-------------------------------------------+ -| Arbiter | _TBD_ | +| Arbiter | Dennis Jen | +---------------+-------------------------------------------+ | Status | Draft | +---------------+-------------------------------------------+ @@ -24,12 +24,12 @@ 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`_. +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`_. Technology Selection ==================== @@ -37,7 +37,7 @@ 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 +* Options for community * Frameworks that are opinionated vs. flexible * Ability to easily build accessible front-ends * Ease of design-framework integration @@ -49,25 +49,25 @@ The following rubric was used to assess potential technologies: * Availability of developers (hiring ability) * Ability to achieve business strategy -In addition, there were a number of key goals that such a technology must +In addition, there were a number of key goals that such a framework must address: * accessibility * internationalization and right-to-left languages * theming * performance -* mobile-first responsive designs +* responsive designs * extensibility / ease of overriding * modularity / scoping * Open edX community interest -* size and activity of the framework's community? +* size and activity of the framework's community * integration with build systems * integration into existing edX pages -Bootstrap is the industry standard web framework with a comprehensive collection -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. +Bootstrap is the industry standard framework for desigining web applications. It +comes with a comprehensive collection of web 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: @@ -91,34 +91,94 @@ 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: +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: + * A partial defining the standard edX fonts, layouts, margins etc * 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 +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. -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. +Important Considerations +======================== + +Bootstrap 4 Alpha Status +------------------------ + +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. + +Right-to-Left Language Support +------------------------------ + +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: + +* Use `bi-app-sass`_ as this is the current technology used by Open edX. This + approach generates two CSS files, one each for LTR and RTL. +* Use `rtlcss`_ which is a CSS postprocessor plugin for `postcss`_. This + approach dynamically adds RTL-specific rules into the CSS file so that it + can handle both directions. + +The `Open edX Front End Working Group`_ discussed both options and decided that +there are several benefits of `rtlcss` over bi-app-sass: + +* The default is for right/left properties to be switched which is usually + the desired result. With bi-app-sass, every property that needs to switch + needs to use a function, and it is very easy to forget to do so. +* For special case situations, rtlcss provides declarative comments that give + the developer to control the behavior. +* Having only a single CSS file that adapts to the desired language + direction makes asset management simpler. + +Given this decision, the reference implementation 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 simplicities sake. + +For more background, see the `Bootstrap RTL Discovery ticket`_. + +Theming and Multi-Tenancy +------------------------- + +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. 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. +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 @@ -143,11 +203,12 @@ The following work was done: * 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 +* RTL support was provided using `postcss`_ and the `rtlcss`_ plugin. 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 +* All 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 of the three converted pages. Note: the proof-of-concept was mostly completed @@ -160,7 +221,7 @@ Rejected Alternatives edX Pattern Library ------------------- -The `edx Pattern Library`_ is an initiative that was started in 2015 to +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 @@ -170,7 +231,7 @@ 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 +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. @@ -184,12 +245,17 @@ 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. +.. _bi-app-sass: https://anasnakawa.github.io/bi-app-sass/ .. _Bootstrap: http://getbootstrap.com/ .. _Bootstrap Proof-of-Concept PR: https://github.com/edx/edx-platform/pull/14834 +.. _Bootstrap RTL Discovery ticket: https://openedx.atlassian.net/browse/FEDX-352 .. _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/ +.. _OEP-11 - Front End Technology Standards: http://open-edx-proposals.readthedocs.io/en/latest/oep-0011.html +.. _Open edX Front End Working Group: https://openedx.atlassian.net/wiki/display/FEDX/Front+End+Working+Group +.. _postcss: http://postcss.org/ +.. _rtlcss: http://rtlcss.com/ .. _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/ From af2d017d1d655c7ea3382c8ff385591e08fdd10d Mon Sep 17 00:00:00 2001 From: Andy Armstrong Date: Thu, 15 Jun 2017 17:54:54 -0400 Subject: [PATCH 3/4] Address feedback --- oeps/oep-0016.rst | 33 ++++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/oeps/oep-0016.rst b/oeps/oep-0016.rst index 5865bd147..8fd690c8b 100644 --- a/oeps/oep-0016.rst +++ b/oeps/oep-0016.rst @@ -24,7 +24,7 @@ Abstract ======== 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 +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 @@ -40,7 +40,7 @@ The following rubric was used to assess potential technologies: * Options for community * Frameworks that are opinionated vs. flexible * Ability to easily build accessible front-ends -* Ease of design-framework integration +* Ease of integration * DIY framework vs. all-inclusive platform * Willingness to dedicate resources to development and maintenance * Ease of prototyping @@ -64,10 +64,10 @@ address: * integration with build systems * integration into existing edX pages -Bootstrap is the industry standard framework for desigining web applications. It -comes with a comprehensive collection of web components that are designed to be -responsive, meaning that Bootstrap applications look good at phone, tablet, -and desktop sizes. +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: @@ -76,15 +76,15 @@ within the edX platform: * It provides a more flexible grid system that supports all of edX's layouts * It uses ems and rems for responsive typography -Another key factor in the switch is the wide availability of Boostrap-based +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 a proprietary markup scheme. XBlock authors -and platform developers alike can target the standard Bootstrap markup which -is very well documented. This saves time in development, and also ensures that +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. Specification @@ -148,13 +148,13 @@ there are several benefits of `rtlcss` over bi-app-sass: * Having only a single CSS file that adapts to the desired language direction makes asset management simpler. -Given this decision, the reference implementation was updated to use `rtlcss`. -This proof-of-concept successfully demonstrated pages rendered right-to-left -which confirmed the choice. +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 simplicities sake. +technology for simplicity's sake. For more background, see the `Bootstrap RTL Discovery ticket`_. @@ -183,7 +183,9 @@ 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. +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. Reference Implementation ======================== @@ -249,6 +251,7 @@ 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 .. _Bootstrap RTL Discovery ticket: https://openedx.atlassian.net/browse/FEDX-352 +.. _Bootstrap 4: https://v4-alpha.getbootstrap.com/ .. _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/ From 002d9ce6c0d1e7374328327d27a2006d447068e2 Mon Sep 17 00:00:00 2001 From: Dennis Jen Date: Mon, 19 Jun 2017 16:37:34 -0400 Subject: [PATCH 4/4] Set accepted status, added resolution field --- oeps/oep-0016.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/oeps/oep-0016.rst b/oeps/oep-0016.rst index 8fd690c8b..b0567a054 100644 --- a/oeps/oep-0016.rst +++ b/oeps/oep-0016.rst @@ -7,18 +7,22 @@ OEP-16: Bootstrap Adoption +---------------+-------------------------------------------+ | Title | Bootstrap Adoption | +---------------+-------------------------------------------+ -| Last Modified | 2017-05-17 | +| Last Modified | 2017-06-19 | +---------------+-------------------------------------------+ | Author | Andy Armstrong | +---------------+-------------------------------------------+ | Arbiter | Dennis Jen | +---------------+-------------------------------------------+ -| Status | Draft | +| Status | Accepted | +---------------+-------------------------------------------+ | Type | Architecture | +---------------+-------------------------------------------+ | Created | 2017-04-18 | +---------------+-------------------------------------------+ +| Resolution | `Original pull request`_ | ++---------------+-------------------------------------------+ + +.. _Original pull request: https://github.com/edx/open-edx-proposals/pull/46 Abstract ========