Table of Contents generated with DocToc
In order to run GENtle locally in development mode, you need to follow these steps:
-
Install node in version
^0.12
. If you have nvm installed, you can runnvm use
. -
Install the
node-foreman
,nodemon
andgulp
node packages globallynpm install -g foreman nodemon gulp
-
Install local npm packages
npm install
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
All compilation tasks use gulp and are defined in
gulpfile.js
and the tasks/
folder.
Stylesheets are writen in SCSS. To compile new changes, run:
gulp css
The compiled stylesheet (public/stylesheets/app.css
) is ignored by git.
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.
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.
We use Karma to run specs written using Jasmine.
Specs are run in PhantomJS so all happens in the CLI.
- Install
karma
and dependencies globallynpm install -g karma karma-phantomjs-launcher karma-requirejs karma-cli karma-jasmine
- Install
phantomjs
globallynpm install -g phantomjs
- Run
karma start
once to start the server - Run
karma run
to run the specs.
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
.
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.
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 |
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 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
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');