Skip to content

Latest commit

 

History

History
207 lines (133 loc) · 6.27 KB

CONTRIBUTING.md

File metadata and controls

207 lines (133 loc) · 6.27 KB

Table of Contents generated with DocToc

GENtle refactor

Getting started

Installation

In order to run GENtle locally in development mode, you need to follow these steps:

  1. Install node in version ^0.12. If you have nvm installed, you can run nvm use.

  2. Install the node-foreman, nodemon and gulp node packages globally

    npm install -g foreman nodemon gulp
  3. Install local npm packages

    npm install

Running the servers

Run both the GENtle server and the documentation server

npm start

Docs will be accessible at http://localhost:8082. It will be automatically refreshed when comments in source files are modified.

GENtle will be accessible at http://localhost:8081

Recompiling assets

All compilation tasks use gulp and are defined in gulpfile.js and the tasks/ folder.

Stylesheets

Stylesheets are writen in SCSS. To compile new changes, run:

gulp css

The compiled stylesheet (public/stylesheets/app.css) is ignored by git.

Javascripts

We use browserify to precompile templates, transform ES6 files and generate the bundle, app.min.js.

To generate an unminified bundle, run:

gulp js

The javascript bundle will automatically be minified in production.

The compiled script (public/scripts/app.min.js) is ignored by git.

The javascript bundle and stylesheets are automatically compiled and minified when deploying, via the postinstall npm hook.

Continuous compilation

To automatically recompile assets when sources change, run:

# Compile everything
npm run build
# Watch and recompile everything
npm run watch
# Watch and recompile stylesheets
gulp css:watch 
# Watch and recompile javascripts
gulp js:watch

JS continuous compilation uses watchify which makes it very quick to update when files changes.

Running specs

We use Karma to run specs written using Jasmine.

Specs are run in PhantomJS so all happens in the CLI.

Installation

  1. Install karma and dependencies globally npm install -g karma karma-phantomjs-launcher karma-requirejs karma-cli karma-jasmine
  2. Install phantomjs globally npm install -g phantomjs

Running the server

  1. Run karma start once to start the server
  2. Run karma run to run the specs.

Server

We use express to route and serve the assets. For now, there is only one route: routes/index.js, serving the views/index.jade jade file.

Any change to express routes or views will trigger a refresh of the server since we use nodemon.

App

The app itself uses browserify to load the different source files and manage dependency injection.

We now use the ES6 module syntax to load modules.

Legacy modules using AMD syntax are still compatible.

Non-NPM module aliases are defined in the package.json file.

Directory structure and primary files

The app (living in public/scripts/) in organised in modules, which will help when developing plugins (not yet implemented).

File/directory Comment
common/ common lib and backbone components
sequence/ main sequence view module
app.js instantiates and starts the app
router.js defines app routes

Each module directory has the following structure:

Directory Comment
lib/ Non-backbone sources
models/ Backbone model and collections. Used to manage data.
templates/ Handlebar templates
views/ Backbone views. Populate templates based on model and handles interaction

Core vendor dependencies

Backbone

We use backbone along with the following plugins:

  • layoutmanager to handle nested views
  • deepmodel to handle nested attributes in models, as a simpler alternative to formal associations

Underscore

Underscore is a backbone dependency but also quite a powerful tool. Custom methods are defined in common/lib/underscore.mixed.js and are automatically mixed in

Handlebars

We use Handlebars for templating in the app.

Helpers are defined in common/lib/handlebar.mixed.js and loaded automatically.

To require and precompile a template, just require/import the html file.

import template from '../templates/sidebar_view.html';
var template = require('../templates/sidebar_view.html');