ITSA customized build

version 1.0.0
home
userguides
Customizing usage on nodejs

If you want to specify which modules to use, you need to setup package.json first. Modules inside package.json can be with or without a slash in their name. Without slash, they will be loaded from npm, without, they will be loaded straight ahead from GitHub.

We decided not to push our modules on npm, because the itsa namespace on GitHub quarantees the right identity of our modules. All ITSA modules can be refered to with "itsa/modulename".

Example package.json:

{
    "name": "myproject",
    "version": "0.0.1",
    "main": "scriptfile.js",
    "dependencies": {
        "event":"itsa/event",
        "io-transfer": "itsa/io/io-transfer.js",
        "node-win":"itsa/node-win",
        "body-parser": "^1.5.2",
        "express": "^4.7.2"
    },
}

After settting up the right package.json, you need to run npm install, which will install all the modules and their dependencies inside the folder node_modules.

Now you can write your application. Be aware that some modules needs to be required as a function with the window-object passed through, something "itsa" does under the hood. When requiring io yourself, you need to use "itsa/node-win" like this:

var window = require('node-win'),

Once everything is setup right, you can start build your scriptfile.

Example scripfile.js:

var express = require('express'),
    bodyParser = require('body-parser'),
    Event = require('event'),
    window = require('node-win'),
    IO = require('io')(window), // needs invokation with window-object
    app = express();

require("io-transfer");

app.use(bodyParser.json({ type: 'application/vnd.api+json' }));

app.get('*', function (req, res) {
    Event.emit('request:start');
    IO.get('http://somedomain.com/?id='+req.param('id')).then(
        function(getresponse) {
            Event.emit('request:recieved');
            res.set('Content-Type', 'text/html').end(getresponse);
        }
    );
});

app.set('port', 8000);

app.listen(app.get('port'), function(){
    console.log("Express server listening on port " + app.get('port'));
});
Customizing usage on the browser

Because the browser doesn't support "require()", you need to bundled loader-file (bundled with Browerify). Browserify inspects your code and creates a single bundle-file that holds all the requirements (and its dependencies) and will define the require()-method in the browser.

Creating your own loader-file takes 4-steps:

1. Creating package.json

The package.json file is just alike the nodejs example above. You can require any "itsa/modulename"-module you want, any subfile, other CommonJS GitHub-modules or npm-modules. You probably be only interested in modules that are build for usage on browser.

Example package.json:

{
    "name": "myproject",
    "version": "0.0.1",
    "dependencies": {
        "polyfill": "itsa/polyfill",
        "event-mobile":"itsa/event-mobile",
        "extend-js": "itsa/extend-js",
        "utils": "itsa/utils",
        "io-transfer": "itsa/io/io-transfer.js",
        "io-xml": "itsa/io/io-xml.js",
        "mathjs": "^1.0.1"
    },
}

The main-property doesn't need to be specified.

2. Run "npm install"

This will install all packages and their requirements into the folder node_modules.

3. Creating builder-file

The builder-file can have any name, as from now, we suppose its name as being index.js. Inside the builder-file, you can use "require()" just the same as within nodejs. You should define only one global namespace (f.e. ITSA) and bind any methods and variables to that one namespace. This namespace should be exported with module.exports.

Example index.js:

require('polyfill');
require('extend-js');

var ITSA = function (config) {
    // notice that "merge()" is delivered by "extend-js"
    ITSA._config.merge(config, true);
    return ITSA;
};

ITSA._config = {
    debug: true,
    base: '/components'
};

ITSA.Event = require('event-mobile')(window); // needs invokation with window-object
require('event/event-emitter.js');
require('event/event-listener.js');

// "utils" has several methods: we merge them all at once:
ITSA.merge(require('utils'));

ITSA.IO = require('io/io-transfer.js')(window); // needs invokation with window-object
require('io/io-xml.js')(window); // needs invokation with window-object

module.exports = ITSA;

Notice that the exported ITSA can be required both as reference as well as a function were you pass through any config-parameters.

4. Bundle builder-file into a loaderfile

The last step is to create the loaderfile using Browerify. Because you need a minified file, you need to minify as well. We use uglifyjs to minify, but you are free to use any minifier you want.

Install browserify, cssify and uglify-js:

If you don't have them yet, install browserify, cssify and uglifyjs on your system globally:

npm install -g browserify
npm install -g cssify
npm install -g uglify-js
By installing it globally, you have the command-line commands available. `cssify` is also automaticly installed locally, for it needs to be there as well.

Create loaderfile:

Final step is to create two build files. One just browserified with all comments and not minified, the second will be minified. You can choose any name you want for these files. Notice that you have to use browserify with the option `-g cssify` to build with css-files. Also notice that we have set specific options to uglify so that the compressed file works with ITSA's code.

browserify -g cssify index.js > build.js
uglifyjs build.js -b ascii_only=true,beautify=false -c drop_debugger,drop_console,warnings=false -m > build-min.js

Get it to the browser

Now you have your custom build-files, you can create your webapp just as easy as:
<script src="/build-min.js"></script>
<script>
    // `ITSA` is available as a global variable
</script>