DETAILS.md

Additional details to supplement the brief nature of the README file.

Table of contents

• Compiling code

• Running docs locally

• Contributors

• Travis CI

• Edge Servers

• Using Bower (ensures you get all the dependencies):

  bower install fuelux
  

  Update with bower update fuelux.

• Using Volo (ensures you get all the dependencies):

  volo add fuelux
  
  

  Update with volo add -f fuelux.

• Clone the Git repository:

  git clone https://github.com/ExactTarget/fuelux/
  

  Cloning the repository ensures you can apply future updates to Fuel UX easily, but requires to you manage its dependencies on your own.

• Download a .zip archive of the latest release.

AMD support

We recommend only loading the controls you need (eg fuelux/checkbox).

If using AMD (such as RequireJS), reference the FuelUX directory in your paths configuration, wherever it is located:

require.config({
    paths: {
        'fuelux': 'http://www.fuelcdn.com/fuelux/3.14.1/'
        //...
    }
});

Then list any individual fuel ux controls needed as dependencies within your application modules:

define(function(require) {
    var spinbox = require('fuelux/spinbox');
    //...
});

In instances where you require every module from Fuel UX, you can use fuelux/all instead of listing each module individually.

Fuel UX also supports placing components in their own <script> tags. Be sure to check component dependencies in the controls documentation and put modules in the correct order if you load them in this method. Errors will appear in the console if you have not loaded dependencies correctly ((Repeater)[http://getfuelux.com/javascript.html#repeater-dependencies] and Scheduler are the only components with dependencies currently).

Compiling code

Fuel UX is lightweight to give you a fast dependable foundation to build upon. It uses Grunt with convenient methods for working with the library. It's how we compile our code, run tests, and more. To use it, install the required dependencies as directed, and then run some Grunt tasks.

Install grunt

From the command line:

Install Dependencies

In terminal from root directory of fuelux repo:

1. npm install
2. bower install

Grunt tasks

Run grunt --help or check out the Gruntfile to see all possible grunt tasks. When contributing, these are the grunt tasks you will be most likely to use:

Serving - grunt serve

Starts a watch server for automated javascript validation and basic tests (JSHint, simplified QUnit) allowing for prototyping at http://localhost:8000/ (not good for unit testing because server catastrophically fails if unit test fails).

Serving - grunt servefast

Starts a watch server allowing for prototyping at http://localhost:8000/ visual review of tests at http://localhost:8000/test/.

Testing - grunt

Runs JSHint and full suite of QUnit tests.

Building dist - grunt dist

This builds the dist directory (compiling your CSS and JS). If you are going to issue a pull request, you should not include changes to the dist directory that are generated from this grunt task.

Troubleshooting dependencies

Should you encounter problems with installing dependencies or running Grunt commands, uninstall all previous dependency versions (global and local). Then, rerun npm install.

Running docs locally

1. If necessary, install Jekyll (requires v2.3.x).

• Windows users: Read this unofficial guide to get Jekyll up and running without problems.

2. Install the Ruby-based syntax highlighter, Rouge, with gem install rouge.
3. From the root /fuelux directory, run jekyll serve in the command line.
4. Open http://localhost:9001 in your browser, and voilà.

Contributors

Giving credit where credit is due.

Major Contributors (a-z)
Adam Alexander
Matt Beard
Bryan Kohlmeier
Dustin McCormick
Christopher McCulloh
Scott Plumlee
Marvin Pribble
Ryan Moore
Steven Rogers
Alex Vernacchia (current)
David Waltz (current)

Travis CI

Pull requests are validate via Travis CI.

Periodically pull requests may fail Travis CI build integration testing with a false negative. If you suspect this is the case you can restart the test via the command line (see below).

Travis downloads the node_modules folder from the "Edge" server ("fuelux-edge") hosted on Heroku. If you add or update a dependency in package.json, you will need to also update package.json in master locally and push it to Heroku for the dependency errors to be resolved in Travis.

Install Travis CI Client

Travis requires ruby and the appropriate ruby gem.

Restarting a Travis CI Build

From the Browser

1. On the Pull Request page on Github, click on the "details" link in the Travis CI build area
2. Click "Login with Github" at the top right of the page
3. Click the "Restart Build" button (circular button with an arrow going in a circle)

From the Command Line

1. Login to Travis In the terminal, issue the following command (You'll need to use your Github credentials):

   travis login --org
   

2. Acquire build number In the terminal, issue the following command:

   travis history
   

3. Restart Build using the build number you obtained from travis history In the terminal, issue the following command:

   travis restart 9999
   

Edge servers

We have an "Edge Server" on Heroku named "fuelux-dev". If you have permissions to the ExactTarget org on Heroku, you can get information on cloning the fuelux-dev remote from its app page on Heroku. If you do not have permissions and believe you should, please contact one of the FuelUX project maintainers.

A build of master is available at https://fuelux-dev.herokuapp.com/dist/js/fuelux.js and https://fuelux-dev.herokuapp.com/dist/css/fuelux.css.

These files should be considered unstable as this is our dev server

To create your own edge server, setup a github web hook on Heroku for this repository and put the app into development mode with heroku config:set NPM_CONFIG_PRODUCTION=false.