Extending packages into Ender

ashnur edited this page May 5, 2012 · 6 revisions

Extending Ender

Extending Ender is where the true power lies! Ender uses your existing NPM package.json in your project root allowing you to export your extensions into Ender. There are three interfaces allowing you to hook into each piece appropriately.

package.json

If you don't already have a package, create a file called package.json in your module root. It 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.

Some important keys to note in this object that are required are name, main, and 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 of course, 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.

The Bridge

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
});

To see this in practice, see how valentine extends Ender.

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>
$.ender({
  rand: function () {
    return this.elements[Math.floor(Math.random() * (this.elements.length + 1))];
  }
}, true);

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

Qwery API

By default Ender has a core set of default packages. One, namely Qwery as the CSS query engine, hooks into the Ender selector interface by setting the privileged _select method. That looks like this:

$._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 remove the selector engine and replace it with this:

$._select = function (selector) {
  return document.querySelectorAll(selector);
};

Existing Ender Packages

If you have an Ender package and would like to add (and brag) it to the rest of the world, please list it the Ender Modules wiki page