HOOKZ
This one was inspired by my favorite hooking system. The best if you will. Hooks API of the ProcessWire CMS.
ProcessWire Hooks + Backbone.Events = hookz
What this have to do with the Backbone.Events, you might ask. Well, I believe that the code for best hooking system I know should be written by one of the best JavaScript coders I am aware of. So I took the code for Backbone.Events and tweaked it to behave like ProcessWire's Hooks API. I even took all the tests for Backbone.Events for testing this very module. And, of course, I added some more.
Install
Install with npm
$ npm install hookz --save
Usage
var hookz = ; var hooker = { console; }; var hookable = { return 'baz'; } hookz;hookz; hooker; hookable; //=> baz boo
API
Constructer
To make a JavaScript object hookable and/or hooker (being able to hook) you call hookz on it. All methods that are properly prefixed will be hookable. Then you call the hookable methods without the prefix and trigger all attached hook methods.
var obj = {}; hookz; obj; // This will trigger all the attached hooks
If you wish to call a hookable method without triggering the hooks attached to it, then you call the method with the prefix. Like this...
obj; // This will not trigger any attached hooks
The syntax is:
hookz;
obj is an object that you want to turn into a hookz object. Which
makes it hookable or being able to add hooks into other hookable objects.
prefix (optional) is used to determine if the method is hookable.
Default is ___
(three underscores).
Note: The methods defined after the call on hookz will not be hookable. First you define your desired object and it's methods, then you call hookz on them. If you want to define hookable methods on the runtime, you can do that with addHook method, see below.
addHook
Adds a hook on a hookable method. Every hookz object has an addHook method.
obj; obj;// => The world is mine!
The syntax is:
obj;
obj is a hookable object. methodName is a name of the method that you want to attach hooks into. callback is a function to be called. context is a context for the callback. Defaults to the object that attaches a hook.
You can provide multiple names at once to attach a hook to several hookable methods. The names should be seperated with space.
obj;
hookz also supports a map syntax for attaching hooks, as an alternative.
obj;
You can provide a context as a third argument when you are attaching hooks via object map syntax.
obj;
If you want to add hookable methods at the runtime, you can do so with addHook method.
obj;
If obj has no method or property called someName
it gets one and it is also
hookable.
removeHook
You can remove the hooks that you have attached with removeHook method.
The syntax is:
obj;
You can remove all the hooks that was attached by an object if you call removeHook with no arguments. Or provide any argument to be more precise. You even can remove hooks with map syntax.
obj;
You can remove all hooks on specific context
obj;
addHookOnce
You can attach a hook so it fires just once with addHookOnce. This one supports all the syntax style as the addHook method.
var counter = 0;var obj = { return this; }; hookz; obj; obj; console;//=> counter is 1
You can also use map syntax with addHookOnce
obj; // Each calback will be invoked once
AddHookBefore & AddHookAfter
If you need a specific hook to run after or before the hookable method, then you can use addHookAfter and addHookBefore methods.
obj;
Both addHookAfter and addHookBefore support all the syntactic sugar that the addHook method does.
HookEvent
All attached hook callbacks get only one argument. A HookEvent object. This object is one of the key concepts of the hookz. It allows you to modify the behavior of the process on the fly.
HookEvent.args
The args property of the HookEvent contains the arguments that were passed into hookable method when invoked.
obj; obj;//=> foo
You can modify the arguments for the next hooks in the chain that were attached into the same hookable method.
obj; obj; obj; //=> callback1: foo//=> callback2: bar
With the before hooks are be able to modify the arguments of the hookable method before it is invoked.
var obj = { console; }; hookz; obj; obj; //=> bar
HookEvent.returnValue
Another useful property that HookEvent has is a returnValue property. Now you can access the value returned by hookable method within all hooks that were attached to it.
var obj = { return 'foo'; }; hookz; obj; obj; //=> obj.a returns foo
Even more, you can change the returned value of the hookable method with the attached hook.
var obj = { return 'The world is'; }; hookz; obj; console; //=> The world is mine!;
HookEvent.obj
obj is another useful property of HookEvent. You can access the object
into which the hook was attached to via HookEvent.obj
.
var hooker = {};var hookable = {}; hookz;hookz; hooker; hookable;//=> true//=> true
Remember? The default context for the callback is the object that attaches the hook.
Coming Soon
- Replace hooks.
- Remove underscore from dependencies.
- A demo app
- Thorough API docs
Test
The test files are not included into the npm package. You need to clone the repo to your machine.
$ git clone https://github.com/dadish/hookz.git$ cd hookz$ npm install$ npm test
License
Credits
- Ryan Cramer, ProcessWire author
- Jeremy Ashkenas, Backbone author