JavaScript — Libraries and guidelines/code style

Most of our UIs are developed in JavaScript using the ExtJS4 framework from Secha (http://sencha.com).

Libraries

At the time of writing, we only use ExtJS4. We are open to including more libraries, but we have not had the need yet.

Guidelines and code style

Indent
4 spaces
Naming

Real meaningful names like:

var age = 10;
var username_to_name_map = {peterpan: 'Peter', wendy: 'Wendy'};

NOT:

var a = 10;
var u = {peterpan: 'Peter', wendy: 'Wendy'};
var usrmap = {peterpan: 'Peter', wendy: 'Wendy'};
Private methods and functions

Same format as semi-private python methods/functions (prefix by _):

_my_private_method: function() {
    return null;
}
Code format
Should pass without any errors from JSHint (see JSHint).
Code layout
The ExtJS app layout. See the devilry_subjectadmin app and the ExtJS4 docs.
Documentation

Use the JSDuck format (https://github.com/senchalabs/jsduck). Note that you do not have to document every single function, but you should at least document:

  • Functions, methods and variables used outside its context (I.E.: you do not have to document view-functions that is only used by its controller, but you have to document it of multiple controllers use it).
  • Properties and config parameters for ExtJS classes.
  • Events for ExtJS classes, especially if they are used outside their controller.
File naming
Name controllers by what the control (E.g: controller/period/PeriodController.js), and the views after their purpose (E.g.: view/period/PeriodOverview.js). Try to use unique names instead of generic names like Overview.js. To see why, try to find (quick open) a file with tens of matches in an IDE like PyCharm or Eclipse that only search for file names, not for folder names (hint: it is not quick to open such files). We learned this when developing devilry_subjectadmin with controllers and views named Overview.js.

JSHint

For info about JSHint, see http://www.jshint.com/.

Install

Install NodeJS and Node Package Manager (part of NodeJS):

  • Ubuntu: sudo apt-get install nodejs npm
  • OSX with homebrew: brew install npm
  • Others, see: http://nodejs.org/

Install JSHint in /usr/local on most nix systems, like Linux and OSX:

$ sudo npm install jshint -g

Usage

Simply point JSHint at a directory:

$ jshint src/devilry_subjectadmin/devilry_subjectadmin/static/devilry_subjectadmin/app/

The defaults are sane (unlike JSLint), so you should not need to supply any options.

Building the ExtJS javascript apps

Note

This is only needed if you have made changes to javascript sources, or if you are making your own ExtJS app.

Building

We use webpack for building javascript. Go into the static directory of the app, where package.json and webpack.develop.js is, and run npm run jsbuild to build for development, and npm run jsbuild-production to build for production. If this is the first time you build javascript for the app, you must run npm install first.

Example:

$ cd devilry/devilry_subjectadmin/static/devilry_subjectadmin
$ npm install
$ npm run jsbuild

During development, you should use:

$ npm run jsbuild-watch

When the code is stable, you should build for production with:

$ npm run jsbuild-production

and commit the changes to production.js and production.js.map

Testing a production build

Change the EXTJS4_DEBUG setting to False in devilry/project/develop/settings/develop.py. This should make all the javascript views serve production.js instead of debug.js.

Update old sencha tools app to build with Webpack

Run the following management command:

$ python manage.py make_require_statements_from_jsb3 <appname> devilry/<appname>/static/<appname>/app.jsb3
$ ... E.g.: ...
$ python manage.py make_require_statements_from_jsb3 devilry_nodeadmin devilry/devilry_nodeadmin/static/devilry_nodeadmin/app.jsb3

This will create an entry.js file with require statements for all the required files extracted from the app.jsb3 file.

Copy the webpack.develop.config.js and webpack.production.config.js files from devilry/devilry_nodeadmin/static/devilry_nodeadmin into the app. Update the package.json file to contain the weback requirements and scripts from devilry/devilry_nodeadmin/static/devilry_nodeadmin/package.json

You should now be able to follow the building guide above. You should now run both npm run jsbuild and npm run jsbuild-production, and commit the generated debug.js, production.js and production.js.map.

The last thing you need to do is to make the view that serves the javascript to inherit from devilry.devilry_extjsextras.views.DevilryExtjs4AppView instead of from Extjs4AppView. You should not need to make any other changes, just switch the superclass of the view.

If the javascript builds, and you have changed the superclass of the view, you should now be able to test the code in your browser. Make sure to check the network tab in chrome developer tools to ensure that the view serves:

  • debug.js instead of app.js with the EXTJS4_DEBUG setting set to True.
  • production.js` instead of ``app-all.js with the EXTJS4_DEBUG setting set to False.

When you have verified that both development and production builds work, you can remove:

  • app-all.js
  • app.jsb3
  • all-classes.js

(they are all replaced by webpack + entry.js).