Using shifter to build a yui module

Overview
A tutorial on creating a yui module using the same build structure as yui. The module will be built using the shifter build tool.

For the purpose of this example we are going to develop a module that represents a cookie (because who doesn’t love cookies).

Please be aware, this tutorial was put together as a way for me to learn the process. It is very possible that there are mistakes or inferences that I have made that will need to be corrected.

Getting started

The first step is to create your directory structure. A minimal module directory looks like this:

    • bakery
      • src
        • cookie
          • js
            • cookie.js
          • build.json

This structure directly parallels yui’s module structure. In this case, bakery is the top level directory that will house both our source files and our built modules.  Once you start building modules, a secondary directory structure called build will appear at the same level as src. build contains your fully built modules.

At this stage, we have built a scaffold for our project. This is the bare minimum structure required to build yui modules. As a matter of fact, the cookie.js and the build.json files are all empty. Just placeholders for the work we are about to do.

Once the scaffold is setup we should setup the build.json file. The build.json file is the equivalent of a makefile and describes the basic components of our module and how they will be built.

The bare minium build.json file looks like this:

name is the name of the module. However, I’m not sure where name is actually used. After you run shifter it will generate a directory in bakery/build called cookie but that name is derived from the key in the builds dictionary.

For a good description of these properties and how they work together see the build.json object reference documentation

At this stage, our module is now sufficiently setup and we can run a build. To build a specific module, cd into the directory with build.json and run shifter.

The output should look like this:

So, what is happening here. First, shifter starts looking for .shifter.json files. A .shifter.json file serves as global configuration for all the modules being built within your working directory. For a description of the types of things you might put into the .shifter.json files read shifter build config.

Next, shifter parses your build file and then looks to see if you have a meta directory and that the meta directory contains a file called <your_js_script_file_name>.json. This meta file is used by YUI when building the loader and is not required for shifter to be able to correctly build your module. Instead you can place your module’s dependencies directly in the build rule for your module.

By adding the “use” list into the “config” entry of the build we are telling shifter that our module will use the “model” module.

And if we look at the contents of our bakery directory we will see that it now looks like this:

    • bakery
      • build
        • cookie
          • cookie.js
          • cookie-min.js
          • cookie-debug.js
          • cookie-coverage.js
    • src
      • cookie
        • just like our intial setup

So, shifter generated the build directory, the module directory and four separate javascript files.

cookie.js is our original javascript src file combined with a little extra code to make it a valid yui module that can be loaded by yui’s Loader. We’ll look at what that means in a moment.  Also, any calls to Y.log have been removed.

cookie-min.js is the same but minified by running UglifyJS This is the javascript that you will typically deploy. cookie.js and cookie-debug.js will be used during testing.

cookie-debug.js is the full original source with all calls to Y.log intact, like cookie.js it still has the extra code needed to make this a valid yui module.

cookie-coverage.js is used as part of the testing process.

Digging into cookie.js

Examining the build directory version of cookie.js it looks like this:

Essentially, any code that you place in src/cookie/js/cookie.js is going to be wrapped in this function call.

So, what is happening here. YUI.add is a static function that adds a module to the YUI instance. This makes the module available through the use statement. The add function accepts four parameters.

The first parameter is the name of the module you are adding.

The second parameter is a function that will be called to define your modules code.
The function will be passed two arguments. The first is the yui instance that the module is being attached to. The second is the name of your module.

The third argument is version string for your module. The version string is currently for informational purposes only. It isn’t used in any way by YUI.

Replacing @VERSION@ with an actual version string

The final argument is an optional configuration dictionary. This dictionary can provide a list of modules that must be loaded before your custom module is loaded:

A list of modules that are used within this module and that should be attached as part of this model:

or a list of optional modules that should be attached if they are already loaded:

Any combination of these keys is also allowed.

More details on YUI.add can be found in the docs.

Making your module do something

The basic principle behind creating a yui module is that you add a namespace to the current YUI instance and export functions or variables through that namespace. For example, if you go back to src/cookie/js/cookie.js and add:

You can now re-run shifter and you will have built your first valid YUI module.

Testing your example
Additional reading
YUI documentation on creating a module
yui-base the lowest level module that all yui modules inherit from
shifter yui’s build tool

LevelsOfThinking