Skip to content

Home

Jump to bottom Edit New page
Brian Talbot edited this page Jan 29, 2016 · 13 revisions

Welcome to the edX UX Pattern Library wiki. We are using this space to communicate working standards, how-tos, and configuration for the static UX Pattern Library work.

Styleguides

How to Work/Develop on the UX Pattern Library Package

If you add or edit any patterns in this repo (found in /pattern-library/) or change any package-centric settings (e.g. package.json or bower.json), please do the following:

  1. test that the change you've made will not negatively affect the node package manager (npm) or Bower packages other apps and codebases are relying on
  2. talk to the UX Team about any bumps (based on semantic versioning) in the npm or Bower packages' version number that are needed.

How to Work and Develop on Documentation Site (PLDOC)

To work on the code of the documentation site portion of this repo, you'll need recent versions of the following things installed on your local machine.

Library Version Purpose
Bundler 1.10 Used to install jekyll and its dependencies
Node.js 0.12.x or 4.0.x Third-party dependency package management
GulpJS + other gulp-based packages 3.9.0 Task runner for build process

Step 1: Install Jekyll

The Pattern Library is managed through Jekyll, a static website generator, so you'll need to install that.

Mac Users

We use a Ruby gem called Bundler to install Jekyll, as that allows us to track the version of Jekyll running on github pages easily.

We assume you have ruby 2.0.0 or later installed. If you don't, an easy way to do that is to use RVM.

With that out of the way, next step is to install bundler, and then to use that to install Jekyll:

$ gem install bundler
$ bundle install

Windows users

Windows users have a bit more work to do, but luckily @juthilo has provided some instructions with his Run Jekyll on Windows guide.

You may also need to install Pygments, the Python syntax highlighter for code snippets that plays nicely with Jekyll (which we use to highlight Front End source code). Read more about this in the Jekyll docs.

Step 2: Install Node.js and Node Package Manager (npm)

The npm command-line tool is bundled with Node.js. If you have it installed, then you already have npm too. If not, go download Node.js.

Step 3: Install Project Dependencies & Gulp Task Flow

From the directory you've checked out this repo into locally, run:

npm install

This runs through all dependencies listed in package.json and downloads them to a node_modules folder in your project directory.

NOTE: You may need to run this more than just once (if encountering errors when running the gulp command) as new dependencies may have been added.

To run the version of gulp installed local to the project, in the root of your this project, run:

./node_modules/.bin/gulp

Step 4: Run Locally (w/ Gulp Workflow)

To view the Pattern Library locally (and to watch for any local changes to content/assets), run the default gulp task with:

gulp

This will run the default gulp task defined in gulpfile.js, which includes the general local development set-up task (build-development) and file/asset watching (watch).

After running the default task, your local instance of the Pattern Library can be viewable at http://localhost:3000. There are additional views:

  • http://localhost:3000/examples/**/* - where full page examples and demos are kept
  • http://localhost:3000/patterns/**/* - permalinks for individually documented pattern library patterns

Committing Code to PLDOC

When developing changes or new work within the PLDOC, please make sure to:

  1. leave the Pattern Library Source Code (contained in pattern-library) unedited (or edit in a separate branch/commit)
  2. run the production preparation-focused gulp task gulp build-production, which will optimize any checked in production assets (styles, images, and scripts), if you've added or heavily edited new PLDOC assets.

How to Use and Deploy the UXPL in your Project

The UX Pattern Library is meant to be a starting UI Framework to support edX and Open edX applications and sites. To start using the UX Pattern Library in an edX/Open edX app, please follow these steps:

Step 0: Install Node

You'll need to download Node.js in order to use either of the UXPL packages.

Step 1: Install and Configure UXPL Packages

Next, you'll want to add the edx-pattern-library registered package as a dependency for your project and install it all at once. You have a few options for what package manager to do that through:

Using Node

In your project's main directory, you'll need to create a package.json file that will manage locally installed npm packages. To create a package.json run:

$ npm init

You'll be walked through some basic settings for your project's package. See also npm's documentation on setting up a package.

Next, you'll want to add the edx-pattern-library registered package as a dependency for your project and install it all at once.

$ npm install edx-pattern-library --save

See also, npm's documentation on installing/saving dependencies.

Using Bower

After instaling Node.js, you can install Bower, a package manager we use to download and maintain many of our vendor and external library refereces.

To install Bower globally:

npm install -g bower

Next, you'll want to add the edx-pattern-library registered package as a bower dependency and install it all at once.

bower install edx-pattern-library --save

NOTE: Bower recommends initializing your project as a bower project in order to manage third party dependencies such as the edx-pattern-library bower package. Bower explains how to do that well with bower.json.

Step 2: Use the UX Pattern Library in your project's Styling

Use the pre-compiled UX Pattern Library CSS files (BETA)

You can use the edX UX Pattern Library as a static CSS base alongside other CSS files. To do so add a reference in the <head> of your app's HTML

<link rel="stylesheet" href="[path to your package manager (npm or bower) or manually managed assets]/edx-pattern-library-ltr.min.css" />

NOTE: The node package manager (npm) package comes with several variations of compiled CSS, including:

  • RTL and LTR support - noted by either a *-ltr or *-rtl suffix.
  • Minified and expanded CSS output formats - for production and development/debugging purposes respectively.

NOTE: This way of using the edX UX Pattern Library is currently in beta is not as widely tested as the Sass method (described below). If you find bugs/issues, please log them.

Reference UX Pattern Library Partials in your Sass Compile

You can also use the edX UX Pattern Library as part of your CSS's Sass compilation (our preferred method). To do so, just import all utilities (see the utilities directory) and what components (see the components directory) you want.

Default Reference/Import

All components and utilities can be imported by default by importing the _edx-pattern-library.scss partial. See the expanded/simplified example below taken from main-ltr.scss and the _build.scss compilation of the edX Pattern Library's Documentation Site:

// ------------------------------
// edX Pattern Library Site: Main Style Compile - LTR

// About: Sass compile for the edX Pattern Library Site. This does not contain styles for other edX products/experiences (e.g. account/onboarding).


// ------------------------------
// #CONFIG - layout direction
// ------------------------------
@import 'ltr';                                                       // LTR-specifc settings and utilities


// ------------------------------
// #CONFIG
// ------------------------------
@import 'config';


// ------------------------------
// #LIB
// ------------------------------
@import 'lib';                                                      // third party libraries
@import '../../../pattern-library/sass/edx-pattern-library';        // UXPL


// ------------------------------
// #EXTENSIONS
// ------------------------------
@import 'utilities';
@import 'components';
@import 'layouts';
@import 'views';
@import 'overrides';

NOTE: Since both libSass and RubySass lack a way to pass in variables/configuration into their @import {file} method, each app is responsible for 1) storing any npm-based dependencies, including the edx-pattern-library, in the best directory structure for that app's set up and 2) creating a _lib.scss partial to import all third party library dependencies from that structure for the Pattern Library to use (see above example).

NOTE: We support right-to-left and left-to-right-based layouts. View more details on what configuration and utilities are needed alongside the UXPL

See the UX Pattern Library Files + Application Files guidelines and example style compile for more examples, details on how to use partials, and general background.

Custom Reference/Import

If you'd like to customize what to import, you can manually import specific elements from the edx-pattern-library package. Here's an example of customizing the default import demo above:

// ------------------------------
// edX Pattern Library Site: Main Style Compile - LTR

// About: **Customized** Sass compile for the edX Pattern Library Site. This does not contain styles for other edX products/experiences (e.g. account/onboarding). Any styles defined in the partials contained here should be prefixed with ".pldoc-" to avoid cascade/run-off into the element stylings.


// ------------------------------
// #CONFIG - layout direction
// ------------------------------
@import 'ltr';                                                       // LTR-specifc settings and utilities


// ------------------------------
// #CONFIG
// ------------------------------
@import 'config';


// ------------------------------
// #LIB
// ------------------------------
@import 'lib';                                                      // third party libraries

// use UXPL's buttons, headings, copy, grid, and layouts
@import '{path to edx-pattern-library package}/pattern-library/sass/patterns/buttons';
@import '{path to edx-pattern-library package}/pattern-library/sass/patterns/headings';
@import '{path to edx-pattern-library package}/pattern-library/sass/patterns/copy';
@import '{path to edx-pattern-library package}/pattern-library/sass/patterns/grid';
@import '{path to edx-pattern-library package}/pattern-library/sass/patterns/layouts';


// ------------------------------
// #EXTENSIONS
// ------------------------------
@import 'utilities';
@import 'components';
@import 'layouts';
@import 'views';
@import 'overrides';
Configure Settings

There are a few places you can start to explore configuring aspects of the UX Pattern Library for your purposes. You can find many configurations and base settings in src/sass/utilities/_variables.scss and can override/customize those in your application's utilities.scss partial (they'll be used throughout the rest of the compile).

NOTE: The code and design contained in the library has not been tested for use alongside other UI Frameworks such as Bootstrap or Foundation.

NOTE: The source code of the Pattern Library does not include any local or production-focused Sass/Front End tooling. It's expected that your app/site has its own Sass compiler (preferrably LibSass).

ewfsdv### vvsvs### vsd## vs

Add a custom sidebar
Clone this wiki locally