selectizer

Selectizer is deprecated!

We have developed a much stable, much usable, much maintainable tool called AlbanilJS. AlbanilJS will replace Selectizer forever, so we won't mantain selectizer any more. If you find yourself here for the first time please go and try AlbanilJS directly. If you are already using selectizer in your project please consider to migrate to AlbanilJS

Selectizer build tool

Based on the Modernizr build process, Selectizer is a build tool made for Node.js that compile javascript projects. It allows the developer to divide an entire project into small javascript files (modules) and then select what pieces of code to include in a specific build, resolving the dependencies automatically (using the Requirejs's optimization tool). The final effect is to get all the selected files (and its dependencies) concatenated into one big deliverable javascript.

This tool gives to the development process two great advantages:

1. The first one is that you can divide your entire project in small chunks of code located in separated files. So, in a way, Selectizer allows you to modularize you code. Ok, that's nice, but.. what about the dependecies? I mean, if you want to put all together some pieces of code into one big deliverable js, there must be a way to specify the order in which these files are arranged, in other words to resolve the dependecies beteween that pieces of code. For this, each module must specify its dependecies, so that Selectizer can resolve them using r.js (the Requirejs's optimization tool). The syntax for specifiying the dependecies is the same as the requirejs.

2. The second one is that you can make custom builds, selecting the modules you want to include. Selectizer will create a final deliverable javascript file with only the specified modules and its dependecies. To specify the modules is needed a configuration file which sytax is detailed below.

How to install it?

It is avaible in npm

$ npm install selectizer

Changes from previous versions

• Diff against 0.1.8:
  • You can specify how to wrap your object through the wrap option of an object's config json.
  • The paths are no longer relative to your project's root directory. Now the paths are relative to the execution source.
  • A bug was solved. The generation process was adding some semicolons to the final build. This is not happening anymore.
  • Now you can return the module you are exponsing as you normaly would do when using RequireJS. This allows you to write AMD unit tests by requiring this modules.
  • The examples were updated accordingly this changes.
  • The dependencies property of an object's config json have changed his name to modules.

How to use it?

First of all, Selectizer works always with objects. This means that when you build something, you are building an object. This is because Selectizer wraps the selected modules and its dependecies into an IIFE and exposes the object through a window.OBJECT = OBJECT assignment.

One important thing to mention is that, at this moment, there is one big constrain that will be solved in future revisions. When you build an object, you are only able to specify internal dependecies. So, for example if you want to build two objects, A and B, and some modules of A depends on some modules of B these are considered external dependencies and then there is no way to manage this kind of situations. You must load the entire B object before A as usually (of course that both of these objects could be builded separately using selectizer, buy you have to resolve the external dependencies manually). This happens because Selectizer can build only one object at a time.

That having said, you can use the Selectizer build tool from the comand line as well as a node module (using require). In both cases it recieves two arguments (specified in order):

• The name of the object you want to build (from now on object folder): Selectizer will always look for a folder named just as the object you want to build. Inside this folder must be a config sub-folder from where Selectizer can obtain the configuration files, and a src sub-folder with all the javascript files (modules) that composes the object.

• Tha path of a folder containing all the object folders: Selectizer will look for any object folder inside this path.

After you generate your build it will be located in the build sub-folder of the object folder.

Configurate

The configuration files are a key part of the Selectizer build process. This is because through these configurations you can select the modules you want to include in a custom build. Also you can specify some fixed code to include always at the bottom of the build.

So, there are two configuration files that must be always inside a sub-folder of your object folder, named config. These are:

• OBJECT.initCode.js: Here you can specify some fixed code that will be always at the bottom of your IIFE's object definition.

• OBJECT.config.json: Here you can select the modules you want to include for a specific custom build. The json itself is an object with two properties:

  • modules: An array of the modules you want to include in a specific build.
  • wrap: You should wrap your object inside of some kind of encapsulation machanism. In order to do this you have the wrap property which is an object composed by two mandatory fields:
    • start: A string specifying the top of the object's wrapper.
    • end: A string specifying the bottom of the object's wrapper.
  • paths (optional): An optional object where you can specify the path of some modules (relative to the src folder). These feature was added to create aliases for the module's paths. Because to define a module you must use the Requirejs syntax, in each module you can specify their dependencies using its paths, but these is a problem if you decide to change the path of some module, because you will have to go into every dependant module and change it as well. With these system for aliasing these problem is solved. But again, its use is only optional.

Example

As you can see the directory arrangment is very important in order to build effective projects. So lets define our properly set folder arrangment.

.
└── objs
    ├── A
    |   ├── config
    |   |   ├── A.initCode.js
    |   |   └── A.config.json
    |   └── src
    |       ├── utils
    |       |   ├── ajaxPost.js
    |       |   └── ajaxGet.js
    |       ├── restCommunication
    |       |   ├── callXApi.js
    |       |   └── callYApi.js
    |       └── vars
    |           └── a_.js
    └── B
        ├── config
        |   ├── B.initCode.js
        |   └── B.config.json
        └── src
            ├── helpers
            |   └── parser.js
            ├── interpreter
            |   ├── getCode.js
            |   └── execute.js
            └── variables
                └── internalB.js

I have created and commited this entire sample directory inside the example folder of this repo, so download it, check it out, and follow the instructions below. You can play with it.

For example, if you want to build the A object using the command line, you should execute:

$ cd [ProjectDirectory]/node_modules/.bin
$ selectizer A ../selectizer/example/objs

Remember that, in node, to execute a command downloaded with npm, you must to execute it from node_modules/.bin.

If you want to use it as a node module then you should do this (supposing that you are saving this javascript file inside your project's root directory):

var gen = require('selectizer');
gen('A', 'node_modules/selectizer/example/objs');

After execute this stuff you will find the build in node_modules/selectizer/example/objs/A/build/A.js

License

Copyright (c) 2014 - 2014 Augusto Altman Quaranta [e-mail] and Matias Carraza [e-mail] et al Licensed under the MIT license.

Contact us

e-mail: [e-mail], [e-mail]