ender

What is this all about?

Ender is an open, powerful, next level JavaScript library composed of application agnostic modules wrapped in a slick intuitive interface. At only 8k Ender can help you build anything from small prototypes to providing a solid base for large-scale rich applications on desktop and mobile devices.

$("p[boosh~=ness]").addClass("clutch").show();

Ender's Jeesh

Ender provides the option to build from any registered NPM packages as well as these 8 powerful core utilities (we call these Ender's Jeesh):

• an expressive Class system
• a fast light-weight selector engine
• a bullet-proof DOM utility
• a multi-platform Event provider
• a dynamic asynchronous script and dependency loader
• a solid http request connection manager
• a slick element animator
• and a core set of utilities provided by underscore
• plus an extension API!

What does ender look like?

DOM queries

$('#boosh a[rel~="bookmark"]').each(function (el) {
  // ...
});

Manipulation

$('#boosh p a[rel~="bookmark"]').hide().html('hello').css({
  color: 'red',
  'text-decoration': 'none'
}).addClass('blamo').after('✓').show();

Events

$('#content a').listen({
  // dom based
  'focus mouseenter': function (e) {
    e.preventDefault();
    e.stopPropagation();
  },

  // dom custom
  'party time': function (e) {

  }
});

$('#content a').click(function (e) {

});

$('#content a').trigger('click party');
$('#content a').remove('click party');

Classes

var Person = $.klass(function (name) {
  this.name = name;
})
  .methods({{
    walk: function () {}
  });
var SuperHuman = Person.extend({
  walk: function () {
    this.supr();
    this.fly();
  },
  fly: function () {}
});
(new SuperHuman('bob')).walk();

AJAX

$.ajax('path/to/html', function (resp) {
  $('#content').html(resp);
});
$.ajax({
  url: 'path/to/json',
  type: 'json',
  method: 'post',
  success: function (resp) {
    $('#content').html(resp.content);
  },
  failure: function () {}
});

script loading

$.script(['mod1.js', 'mod2.js'], 'base', function () {
  // script is ready
});

// event driven. listen for 'base' files to load
$.script.ready('base', function () {

});

Animation

// uses native CSS-transitions when available
$('p').animate({
  opacity: 1,
  width: 300,
  color: '#ff0000',
  duration: 300,
  after: function () {
    console.log('done!');
  }
});

Utility

Utility methods provided by underscore are augmented onto the '$' object. Some basics are illustrated:

$.map(['a', 'b', 'c'], function (letter) {
  return letter.toUpperCase();
}); // => ['A', 'B', 'C']

$.uniq(['a', 'b', 'b', 'c', 'a']); // => ['a', 'b', 'c']

$[65 other methods]()

No Conflict

var ender = $.noConflict(); // return '$' back to its original owner
ender('#boosh a.foo').each(fn);

Your Module Here

Remember, the Jeesh is here just to get you started!

$.myMethod(function() {//does stuff});

How to get started

Ender pulls together the beauty of well-designed modular software in an effort to give you the flexibility and power to build a library which is right for your individual projects needs.

Uniquely, if one part of your library goes bad or unmaintained, it can be replaced with another with minimal to zero changes to your actual application code! Furthermore if you want to remove a feature out entirely (like for example, the animation utility or classes), you can use the Ender command utility and compose only the modules you need.

Building With Ender

Building ender is super easy.

To start, if you haven't already, install NodeJS and NPM. Then to install just run:

$ npm install ender

//or if you're using npm 1.0 rc

$ nmp install ender -g

This will install Ender as a command line tool. Once Ender is installed you have four methods at your disposal: build, just, async, and help.

Build

Build is the standard method for Ender bundling. To use it, simply navigate to the directly you would like to build into and run something like:

$ ender build scriptjs,qwery,underscore

//or

$ ender -b scriptjs qwery underscore

(note: you may either comma separate or space separate your ender packages... which ever you prefer.)

This should generate both an ender.js file (for dev) as well a an ender.min.js (for prod).

(note: This will also generate a node_modules folder... keeping this, will speed up building in the future if you plan on adding additional packages. However, feel free to remove it if you'd like. See just method for building without this folder.)

Just

The just method is exactly the same as build, except it will remove the node-modules folder after it has completed building. Use this if you don't plan on rebuilding ender multiple times or are worried about directory sizes. Using just, looks like:

$ ender just scriptjs,qwery,underscore

//or

$ ender -j scriptjs qwery underscore

Async

The async method is really freaking awesome! Use this to build a custom ender library which loads all it's modules async using script.js!! Wow. To build all you have to do is something like:

$ ender asyc domready qwery bean

//or

$ ender -a domready qwery bean

Each module is then loaded using script.js's "new school" async style of loading. You can then hook into ender's ready method, to know when you can start using ender!!

$.ready('ender', function() {
  //all ender packages loaded async...
  $('#container').emit('click');
});

(note: a module must have a bridge file to be asynchronously loaded);

If you are unfamiliar with the script.js api, you can read up more on it here.

(note: There is no need to include script.js when using the async build method -- it will be included by default)

help

Help gives you a simple run through of the available methods. More documentation will likely be added here down the line.

NPM

If you haven't realized already, ender is leveraging npm to lots of stuff! So, if you're new to NPM, it's a good idea to read Isaac's Intro to NPM. Also, remember, ender is only as up to date as your last npm update.

Extending Ender

Extending Ender is where the true power lies! Ender leverages your existing NPM package.json in your project root allowing you to export your extensions into Ender.

package.json

If you don't already have a package, create a file called package.json in your module root. This might also be a good time to register your package with NPM (This way others can use your awesome ender module (it also guarantees bragging rights))! A completed package file should look something like this:

{
  "name": "blamo",
  "description": "a thing that blams the o's",
  "version": "1.0.0",
  "homepage": "http://blamo-widgets.com",
  "authors": ["Mr. Blam", "Miss O"],
  "repository": {
    "type": "git",
    "url": "https://github.com/fake-account/blamo.git"
  },
  "main": "./src/project/blamo.js",
  "ender": "./src/exports/ender.js"
}

Have a look at the Qwery package.json file to get a better idea of this in practice.

An important thing to note in this object is that ender relies on the properties name, main, and ender. Both Name and Main are already required by NPM, however the ender property is (as you might expect) unique to Ender.

name -- This is the file that's created when building ender.

main -- This points to your main source code which ultimately gets integrated into Ender. This can also be an array of files:

"main": ["blamo-a.js", "blamo-b.js"]

ender -- This special key points to your bridge, which tells Ender how to integrate your package! This is where the magic happens. If you don't provide a bridge with the ender property, or if you're trying to include a package which wasn't intended to work with Ender, no worries! Ender will automatically default to a CommonJS module integration and automatically add the exported methods directly to ender as top level methods. More on this below.

Packaging without publishing

If you you're not ready to publish your package, but you're ready to test it's integration with ender, don't worry. Simply create the package.json file, as if you were going to publish it, then navigate into the root of your directory and run:

$ npm install

This will register a local only copy of your package, which ender will use when you try to build it into your library later:

$ ender -b qwery,bean,myPackage

The Bridge

The bridge is what ender uses to connect modules to the main ender object -- it's what glues together all these otherwise independent packages into your awesome personalized library!

Top level methods

To create top level methods, like for example $.myUtility(...), you can hook into Ender by calling the ender method:

$.ender({
  myUtility: myLibFn
});

(note - this is the default integration if no bridge is supplied)

The Internal chain

Another common case for Plugin developers is to be able hook into the internal collection chain. To do this, simply call the same ender method but pass true as the second argument:

$.ender(myExtensions, true);

Within this scope the internal prototype is exposed to the developer with an existing elements instance property representing the node collection. Have a look at how the Bonzo DOM utility does this. Also note that the internal chain can be augmented at any time (outside of this build) during your application. For example:

<script src="ender.js"></script>
<script>
// an example of creating a utility that returns a random set of elements
$.ender({
  rand: function () {
    return this.elements[Math.floor(Math.random() * (this.elements.length + 1))];
  }
}, true);

$('p').rand();
</script>

Selector Engine API

Ender also exposes a unique privileged variable called $._select, which allows you to set the Ender selector engine. Setting the selector engine provides ender with the $ method, like this:

$('#foo .bar')

Setting the selector engine is done like so:

$._select = mySelectorEngine;

You can see it in practice inside Qwery's ender bridge

If you're building a Mobile Webkit or Android application, it may be a good idea to simply set it equal to QSA:

$._select = document.querySelectorAll;

Get started with the default build

If you're looking to test drive Ender with its default modules, have a play with the compiled source

Why all this?

Because in the browser - small, loosely coupled modules are the future, and large, tightly-bound monolithic libraries are the past. As we like to say, only use what you need, when you need it.

Also, micro-utilities keep you out of having to rollback entire frameworks due to bugs found in individual parts. Instead you can simply compose the modules you want, at any version, in any combination! For example if there is a bug in klass @ version 1.0.6, you can rollback:

$ npm activate klass@1.0.5

In the same notion, you also get the advantage of being able to upgrade in small portions! For example if there are features you wish to use in a micro-release, you can simply update the module, then rebuild:

$ npm update klass
$ ender -b

License

Ender (the wrapper) is licensed under MIT - copyright 2011 Dustin Diaz & Jacob Thornton

For the individual modules, see their respective licenses.

Contributors

• Dustin Diaz @ded
• Jacob Thornton @fat