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 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

This will install ender as a command line tool. From here, navigate to the directly you would like to build into and run something like:

$ ender -b scriptjs,qwery,underscore

This should generate both an ender.js file (for dev) as well a an ender.min.js (for prod). For the default Jeesh, run the ender command with the -b option without arguments:

$ ender -b

which is synonymous to:

$ ender -b qwery,bean,bonzo,klass,reqwest,emile,scriptjs,domready,underscore

Remember, Ender is only as recent as your latest NPM update. If you're new to NPM, it's a good idea to read Isaac's Intro to NPM

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;

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