diff --git a/docs/bootstrap.rst b/docs/bootstrap.rst new file mode 100644 index 0000000000..549a96955b --- /dev/null +++ b/docs/bootstrap.rst @@ -0,0 +1,88 @@ +.. _ui_bootstrap: + +###################### +Working with Bootstrap +###################### + +This topic describes the Bootstrap framework, and how it should be used to +build user interfaces within edX applications. Note that Bootstrap adoption +started after the Ginkgo release, and so this document applies to the edX +master branch and to the forthcoming Hawthorn release. + +If you are interested in the rationale for edX choosing Bootstrap, you can +read about the decision in `OEP-16: Adopting Bootstrap +`_. + +.. highlight:: none + +*************** +Getting Started +*************** + +Bootstrap is an open source front end component library that is used by many of +the world's most popular applications. It allows for rapid assembly of front end +components using a responsive grid system, a robust component library and easy +to configure theming capabilities to ensure that new components are rendered +consistently. EdX is using `Bootstrap 4`_ which is a reimplemented version using +Sass and that is currently in beta release. + +All edX applications should use the `edx-bootstrap`_ package that can be +installed via `npm`_. This package provides two themes (a default Open edX +theme, as well as an edX branded version), and eventually will provide custom +Open edX styles for common patterns. + +.. _ui_bootstrap_custom_designs: + +************************* +Developing Custom Designs +************************* + +Bootstrap provides a large number of components and layouts out-of-the-box, but +there will always be a need to implement custom designs. There are a number of +considerations to take into account when implementing your designs using Sass. + +The most important rule is to avoid hard-coding values such as colors and fonts. +Using hard-coded values means that Bootstrap themes will not be able to affect +your styles, and so your new elements will look out of place. Whenever possible +you should instead use the functions and variables provided by Bootstrap to +access theme colors or fonts. See `Bootstrap customization options`_ for more +details. + +For example, here is an example of a hard-coded style:: + + .my-element { + font-family: "Open Sans"; + color: #0000ff; + } + +The recommended alternative is as follows:: + + .my-element { + font-family: $font-family-sans-serif; + color: theme-color("primary"); + } + +If you do find the need for a custom color or font that isn't provided by +the edX Bootstrap library, consider first whether it makes sense to contribute +it back so that other applications can use this value too. If you decide to +add a custom value, define it as a variable that can be overridden by a theme by +using the ``!default`` flag. This allows themes to provide a different value +for this variable if they choose. See the Sass documentation for `default flag`_ +for more details. + +For example:: + + $my-custom-color: #0000ff !default; + + .my-element { + font-family: $font-family-sans-serif; + color: $my-custom-color; + } + + + +.. _Bootstrap 4: https://getbootstrap.com/docs/4.0/getting-started/introduction/ +.. _Bootstrap customization options: https://getbootstrap.com/docs/4.0/getting-started/options/ +.. _default flag: http://sass-lang.com/documentation/file.SASS_REFERENCE.html#Variable_Defaults___default +.. _edx-bootstrap: https://www.npmjs.com/package/@edx/edx-bootstrap +.. _npm: https://www.npmjs.com/ diff --git a/docs/javascript.rst b/docs/javascript.rst new file mode 100644 index 0000000000..4c0104a927 --- /dev/null +++ b/docs/javascript.rst @@ -0,0 +1,110 @@ +JavaScript in edx-platform +========================== + +ES2015 +------ + +All new JavaScript code in edx-platform should be written in ES2015. +ES2015 is not a framework or library -- rather, it is the latest and +greatest revision of the JavaScript language itself, natively supported +in all modern browsers and engines. Think of it as JavaScript's +equivalent to Python 3. ES2015 brings with it number of wonderful +syntactic features, such as classes, native imports, arrow functions, +and new data structures. To learn more about ES2015, check out `Luke +Hoban's comprehensive ES6 Features +repo `__. + +Although ES2015 is natively supported in modern browsers, older browsers +can't interpret it. Here at edX, we support the two latest versions of +every browser, plus IE11, so we need to do a little extra work to +support ES2015. This is where Webpack and Babel come in. Webpack is a +module bundler that transforms, minifies, and compiles frontend code +into pre-built "bundles" to include within pages. It works together with +Babel to transpile ES2015 code into ES5 code, which can safely be used +in all browsers. + +Fortunately, you don't need to worry about the gritty details of Webpack +in order to write ES2015 code. You just need to make sure Webpack knows +where to find your files. It's also important to note that **Webpack is +not compatible with RequireJS**. Work is currently underway to move all +legacy RequireJS modules into Webpack, but until it is complete, you +will need to update legacy code yourself in order to use it with ES2015. + +Adding a New ES2015 Module +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Don't mix ES2015 and ES5 modules within directories. If necessary, +create a new directory just for your new file. If you create a new +directory, run the following from edx-platform root to copy over an +appropriate eslint config: + +:: + + cp cms/static/js/features_jsx/.eslintrc.js path/to/your/directory + +Give your new file an UpperCamelCase filename, such as +``MyAwesomeModule.js``. If it is a React module, use the ``.jsx`` +extension; otherwise, use the ``.js`` extension. + +If you intend to include this module itself directly within a page, you +will need to tell Webpack about it. Add a line to the ``entry`` object +within ``webpack.common.config.js``. + +:: + + 'MyAwesomeModule': 'path/to/your/directory/MyAwesomeModule.js', + +The new entry's key should be the name of your module (typically this is +the same as your filename), and its value should be the path to your +file relative to the edx-platform root. + +Writing Your File +~~~~~~~~~~~~~~~~~ + +Structure your module using ``class``\ es. Typically, you'll want to +define and export one ``class`` per file. If you are going to be +including this module directly within a page and passing it through +Webpack, use a non-default export. ``MyAwesomeModule.js`` should look +something like this: + +:: + + export class MyAwesomeModule { + // your awesome code here + } + +Use two-space indentation. This is industry standard practice for +ES2015. If you need to pull in external dependencies, use ``import`` +statements: + +:: + + import moment from 'moment'; + import 'jquery.cookie'; + import { MyOtherModule } from './MyOtherModule'; + +Building Your File +~~~~~~~~~~~~~~~~~~ + +Devstack comes with two watcher containers specifically for building +assets. They compile frontend files very quickly, so you can see your +changes reflected in a browser almost immediately. You can run these +containers with: + +:: + + make dev.up.watchers + +and stop them with + +:: + + make stop.watchers + +If you make any changes to ``webpack.common.config.js`` while the +watchers are running, you will need to restart the watchers in order for +them to pick up your changes. + +If your changes aren't being reflected in the browser, check the logs +with ``make logs`` to see if something went wrong. If you get stuck, ask +for help in the FedX hipchat room, or in #front-end on Slack.