YUI Shifter tool

As I continue to delve into the depths of YAHOO’s UI JavaScript library, the more I am thrilled at the level of support that they put behind their tools. Hopefully I can share my experience with bypassing the previous YUI Builder tool and moving directly to the new Shifter tool.

At first the YUI Builder was made available to compile all custom YUI modules. This tool was built upon Apache Ant which integrated well with Eclipse at the cost of setup. Plus, the project was stuck using Ant instead of another build tool. Over past years, YUI has been implementing support for NodeJS so transition the Shifter tool on NodeJS was a no-brainer.

I would highly recommend using YUI Yogi to jump start your module. You can read more here.

Setup
Platform : Windows 8
NodeJS : v0.8.16
Shifter : 0.2.18
Shifter : 0.2.25

After installing NodeJS, please run these commands:

  npm -g install shifter
  shifter -v

Directory Setup
Use the YUI Yogi tool to create the module’s directory structure. The project directory should look like this:

-src
  -module 1
    -js
    -meta
  -and again for each module...

.shifter.json Configuration
The .shifter.json file defines how the project should be built. This is one of the more important files to build multiple modules, but the documentation on the YUI site seems to be scattered. This file is hosted on GitHub project page, but I will include it here:

{
    "silent": false,
    "istanbul": true,
    "build-dir": "./tests/assets-global/"
}


Please copy this file to the src directory. Please copy this to the project directory.

Let’s configure this file for our project directory. I will assume that you are familiar with the configurations.

{
    "silent": false,
    "istanbul": false,
    "build-dir": "../build",
    "build-dir": "./build",
    "walk": "walk",
    "recursive": "recursive"
}


Update: I have added the recursive parameter and updated the build-dir parameter to reflect this change.

Our First Module
Let’s create our module called Hello. From here on, I will assume you can create modules in your sleep. =] If not, please look here.

Please create and place hello.js inside the js folder.

-src
  -hello
    -js
      -hello.js
    -meta

Example module:

var Hello = function () {
    'use strict';
    Hello.superclass.constructor.apply(this, arguments);
};
Hello.NAME = 'Hello';
Hello.ATTRS = {
    msg : {
        value : "Hello world!",
        validator : Y.Lang.isString
    }
};
Y.extend(Hello, Y.Base, {
    initializer : function () {
        Y.log(this.get('msg'));
    }
});

Meta JSON file
Please create and place a hello.json file inside the meta directory. This file defines how the module should be loaded on the user interface side.

-src
  -hello
    -js
      -hello.js
    -meta
      -hello.json

Please refer here for more information. We can define the modules by either one for each JavaScript file in this format:

{
  "hello" : {
    "requires" : [ "base" ],
    "skinnable" : false
  }
}

Or one with a collection of the submodules like this:

{
  "hello" : {
    "submodules" : {
      "hello" : {
        "requires" : [ "base" ],
        "skinnable" : false
      },
      "submodule2" : {
        "requires" : [ "base" ],
        "skinnable" : true
      }
    }
  }
}

build.json
Now we need to indicate how this module should be built. Please create a file called build.json file inside the hello directory.

-src
  -hello
    -js
      -hello.js
    -meta
      -hello.json
    -build.json

The build file should look as follows:

{
  "name" : "hello",
  "builds" : {
    "hello": {
      "jsfiles": [ "hello.js" ],
      "skinnable" : false
    },
    "submodule2": {
      "jsfiles": [ "hello.js" ],
      "skinnable": true
    }
  }
}

Build the modules
Please follow these commands to build your module:

  cd ~/project/
  cd src
  shifter


Update: With the recursive parameter in the .shifter.json, changing to the src directory is not necessary.

After this a successful build, the compiled script will be located in the project directory.

-build
  -hello
    -hello.js
    -hello-coverage.js
    -hello-debug.js
    -hello-min.js
  -submodule2
    -submodule2.js
    -submodule2-coverage.js
    -submodule2-debug.js
    -submodule2-min.js
-src
  -hello
    -js
      -hello.js
      -submodule2.js
    -meta
      -hello.json
    -build.json

Automatically build modules
We want to avoid invoking the shifter tool after every single change. Not only are we incurring a running cost, but we are losing development time running the tool. Hence let’s run the watch to automatically build the scripts upon each change:

  cd ~/project/
  shifter --watch

Edit on Janurary 16th:
— Added the recursive parameter to the .shifter.json properties. Now we don’t have to change to the src file to run the shifter tool!

Edit on March 5th:
— Edited the build.json and the meta/*.json file section for clarity.
— Added how to automatically build the modules.
— Updated Shifter tool to 0.2.25

Advertisements