yui3boiler

simple nodejs utility to initialize module source directory structure and templates for yui3 modules

All code is licensed under both the MIT and BSD licenses, presented in LICENSE.

API Documentation

Installing

Use npm:

npm install yui3boiler

Usage

Use in a node application:

var Y = require('yui3boiler'),
    b;

b = new Y.BOILER.Base({
  attrs: ['foo', 'bar', 'baz'],
  classname: 'Foo',
  name: 'foo',
  requires: 'array-extras,node,base',
  skinnable: ['ryan', 'sam'],
  srcdir: '/Users/Ryan/repos/github/ryanvanoss/yui3/src/'
});
b.boil();

Creates the following in /Users/Ryan/repos/github/ryanvanoss/yui3/src/, assuming /Users/Ryan/repos/github/ryanvanoss/yui3/src/ exists, and /Users/Ryan/repos/github/ryanvanoss/yui3/src/foo does not exist:

src
  foo
    assets
      foo-core.css
      skins
        ryan
          foo-skin.css
        sam
          foo-skin.css
    build.properties
    build.xml
    HISTORY.md
    js
      foo.js
    meta
      foo.json
    README.md
    tests
      yuitest
        foo-tests.js
        foo.html

Use from the command line:

The yui3boiler config options aren't really conducive to command line usage. If you want to use it outside of a node application, just make sure you've installed it, then you can simply create a js file with the same code as above and run:

node myfile.js

Building or Modifying

Get the source:

git clone git@github.com:ryanvanoss/node-yui3boiler.git

Clone the yui builder project as a sibling to your source directory:

git clone git://github.com/yui/builder.git

Alternatively, you can download Builder as a zip directly. Just make sure you unzip it to the correct location.

Install ant 1.8+.

Download ant from the ant project download page, and make sure that you add it to your path.

cd to the root of the project:

cd /path/to/yui3boiler/

Install the dev dependencies (see package.json for full list):

npm install buffertools
npm install handlebars
npm install yui
npm install yuidocjs

See the npm FAQ if you're confused on why these aren't installed with the global (-g) flag.

Run the ant build.

If you want to change the default properties, make a copy of build-DEFAULTS.properties and name it build-OVERRIDES.properties. Edit any properties you'd like to change, and comment out, or leave unchanged, any properties that you would like to inherit the defaults. The build file includes both property files automatically. It includes build-OVERRIDES.properties first. Since ant properties are immutable, any properties that you set in build-OVERRIDES.properties will take precedence over the properties from build-DEFAULTS.properties. By default, all built files will be output to the out directory in the base directory of the project. You can override this location by setting the appropriate properties as explained above. The default target is build.

ant

Build Targets

build: Builds all components of the project. Calls clean, mods, tpls, tests, cleanup.

ant build

clean: Removes any temporary directories created by the build, as well as the dir.out directory.

ant clean

cleanup: Removes any temporary directories created by the build. Does not remove the dir.out directory.

ant cleanup

docs: Builds all documentation. Currently the same as yuidoc, but available as a general doc-building target in the case that more, non-yuidoc, documentation is necessary in the future.

ant docs

mods: Builds all js modules.

ant mods

runtests: Creates an npm package, installs it locally (does not push it to npm), then builds all tests and runs them with the new package.

ant runtests

tests: Builds all tests.

ant tests

tpls: Builds (i.e. copies) all raw templates and creates a single compiled Handlebars js template file, using the filenames as the template names.

ant tpls

yuidocs: Builds API documentation from js source using yuidocjs.

ant yuidocs

Remember that you can call multiple targets at once in ant, so the following also works:

ant clean runtests docs

TODOS

1. Fix doc output so that BOILER.Base correctly shows everything it inherits.
2. Add documentation for ATTRS in each class.
3. Generate module data in yui3boiler.js.
4. Update tests to test for the appropriate message when intentionally erroring.
5. Update tests to run a linter on the generated source files to make sure that they are valid js.
6. Consider adding ability to generate full js files by consuming object literal containing API outline. E.g.

{
  methods: {
    instance: {
      foo: {
        arguments: {
          'bar': {
            description: 'Lorem ipsum...',
            optional: true,
            type: 'string'
          }
        },
        description: 'Lorem ipsum...'
      }
    },
    static: {
      foo: {
        arguments: {
          'bar': {
            description: 'Lorem ipsum...',
            type: 'string'
          }
        }
      }
    }
  }
}

1. Setup tests on travis-ci.
2. Remove home grown fs operations (mkdirpSync, rimrafSync).
3. Remove all *Sync calls... sigh
4. Create ant deploy target to pull files from git, runtests, upload zip to git and push to npm.
5. Write more tests.
6. Determine whether or not to create all files listed in this.get('cssfiles') and this.get('jsfiles').
7. DRY with regard to templates build code. Currently it's repeated in the global build and build-DEFAULTS.properties files with only slight modifications.
8. Build the README code examples, and add tests for them so that they're always up to date (and valid...).