literate-docs/struck.html
<!DOCTYPE html>
<html>
<head>
<title>struck.js</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta name="viewport" content="width=device-width, target-densitydpi=160dpi, initial-scale=1.0; maximum-scale=1.0; user-scalable=0;">
<link rel="stylesheet" media="all" href="docco.css" />
</head>
<body>
<div id="container">
<div id="background"></div>
<ul class="sections">
<li id="title">
<div class="annotation">
<h1>struck.js</h1>
</div>
</li>
<li id="section-1">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-1">¶</a>
</div>
</div>
<div class="content"><div class='highlight'><pre>(<span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(root, factory)</span> </span>{
<span class="hljs-keyword">if</span> (<span class="hljs-keyword">typeof</span> define === <span class="hljs-string">'function'</span> && define.amd) {
define([<span class="hljs-string">'lodash'</span>, <span class="hljs-string">'jquery'</span>, <span class="hljs-string">'exports'</span>], <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(_, $, exports)</span> </span>{
root.Struck = factory(root, exports, _, $);
});
} <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> (<span class="hljs-keyword">typeof</span> exports !== <span class="hljs-string">'undefined'</span>) {
<span class="hljs-keyword">var</span> _ = <span class="hljs-built_in">require</span>(<span class="hljs-string">'lodash'</span>), $ = <span class="hljs-built_in">require</span>(<span class="hljs-string">'jquery'</span>);
exports = factory(root, exports, _, $);
} <span class="hljs-keyword">else</span> {
root.Struck = factory(root, {}, root._, root.jQuery);
}
}(<span class="hljs-keyword">this</span>, <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(root, Struck, _, $)</span> </span>{</pre></div></div>
</li>
<li id="section-2">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-2">¶</a>
</div>
<h3 id="utilities">Utilities</h3>
</div>
<div class="content"><div class='highlight'><pre>
<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">capitalize</span><span class="hljs-params">(string)</span> </span>{
<span class="hljs-keyword">return</span> string.charAt(<span class="hljs-number">0</span>).toUpperCase() + string.slice(<span class="hljs-number">1</span>);
}</pre></div></div>
</li>
<li id="section-3">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-3">¶</a>
</div>
<h5 id="splitname">splitName</h5>
<p>split “event1 event2” into an
array of event names</p>
</div>
<div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">splitName</span><span class="hljs-params">(names, context)</span> </span>{</pre></div></div>
</li>
<li id="section-4">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-4">¶</a>
</div>
<p>get result of name if defined as a function</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">var</span> events = result(names, context);</pre></div></div>
</li>
<li id="section-5">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-5">¶</a>
</div>
<p>split by spaces if result isn’t an array
always returns an array</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">return</span> _.isArray(events) ? events : events && events.split(<span class="hljs-string">' '</span>);
}</pre></div></div>
</li>
<li id="section-6">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-6">¶</a>
</div>
<h5 id="result">result</h5>
<p>returns get result of an expression</p>
</div>
<div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">result</span><span class="hljs-params">(expr, context)</span> </span>{
<span class="hljs-keyword">return</span> _.isFunction(expr) ? expr.apply(context) : expr;
}
<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">firstDef</span><span class="hljs-params">()</span> </span>{
<span class="hljs-keyword">return</span> _.find(<span class="hljs-built_in">arguments</span>, <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(arg)</span> </span>{
<span class="hljs-keyword">return</span> !_.isUndefined(arg);
});
}</pre></div></div>
</li>
<li id="section-7">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-7">¶</a>
</div>
<h2 id="hook">Hook</h2>
</div>
</li>
<li id="section-8">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-8">¶</a>
</div>
<p>wraps function calls with hook logic,
used to wrap method calls in an Struck
Object. The object’s hook function will be
called before and after the function call
by default </p>
</div>
</li>
<li id="section-9">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-9">¶</a>
</div>
<p><strong>Example:</strong></p>
<pre><code class="lang-javascript">var HookedObj = Struck.EventObject.extend({
initialize: function () {
this.com.on('beforeSayHello', function() {
console.log('open mouth');
});
},
sayHello: Struck.hook(function () {
console.log('say hello');
})
})
var myHookedObject = HookedObj.create({
onSayHello: function() {
/ console.log('hello complete);
},
afterSayHello: function () {
console.log('close mouth');
}
});
myHookedObject.sayHello();
output:
- open mouth
- say hello
- hello complete
- close mouth
</code></pre>
</div>
<div class="content"><div class='highlight'><pre>
Struck.hook = (<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">()</span> </span>{
<span class="hljs-keyword">var</span> defaults = {
prefix: <span class="hljs-string">'on'</span>,
pre: <span class="hljs-string">'before'</span>,
post: <span class="hljs-string">'after'</span>,
method: <span class="hljs-string">'hook'</span>
};
<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">fire</span><span class="hljs-params">(self, method, opts)</span> </span>{
<span class="hljs-keyword">if</span> (self[method]) {
self[method].call(self, opts.name, opts.prefix, opts.args);
}
}
<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">Hook</span><span class="hljs-params">(name, func, opts)</span> </span>{
<span class="hljs-keyword">var</span> options = _.extend({}, defaults, !_.isFunction(func) ? func : opts);
<span class="hljs-keyword">var</span> fireDefaults = {
name: name,
prefix: options.prefix
};</pre></div></div>
</li>
<li id="section-10">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-10">¶</a>
</div>
<p>define function to called as a method of
Struck Object, the <code>this</code> context is assumed
to refer to the struck object.</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">return</span> <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">()</span> </span>{
<span class="hljs-keyword">var</span> args = _.toArray(<span class="hljs-built_in">arguments</span>),
result;
<span class="hljs-keyword">var</span> fireOptions = _.extend({}, fireDefaults, { args: args });
<span class="hljs-keyword">if</span> (options.pre) {
fire(<span class="hljs-keyword">this</span>, options.method, _.extend({}, fireOptions, { prefix: options.pre }));
}
<span class="hljs-keyword">if</span> (_.isFunction(func)) {
result = func.apply(<span class="hljs-keyword">this</span>, <span class="hljs-built_in">arguments</span>);
}
fire(<span class="hljs-keyword">this</span>, options.method, fireOptions);
<span class="hljs-keyword">if</span> (options.post) {
_.defer(fire, <span class="hljs-keyword">this</span>, options.method, _.extend({}, fireOptions, { prefix: options.post }));
}
<span class="hljs-keyword">return</span> result;
};
}
<span class="hljs-keyword">return</span> Hook;
})();</pre></div></div>
</li>
<li id="section-11">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-11">¶</a>
</div>
<h3 id="extend">Extend</h3>
</div>
</li>
<li id="section-12">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-12">¶</a>
</div>
<p><em>Pulled from Backbone.js 1.1.2 source</em></p>
<p>Helper function to correctly set up the prototype chain,
for subclasses. Similar to goog.inherits, but uses a hash
of prototype properties and class properties to be extended.</p>
</div>
<div class="content"><div class='highlight'><pre>
Struck.extend = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(protoProps, staticProps)</span> </span>{
<span class="hljs-keyword">var</span> parent = <span class="hljs-keyword">this</span>;
<span class="hljs-keyword">var</span> child;</pre></div></div>
</li>
<li id="section-13">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-13">¶</a>
</div>
<p>The constructor function for the new subclass is either defined
by you (the “constructor” property in your extend definition),
or defaulted by us to simply call the parent’s constructor.</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">if</span> (protoProps && _.has(protoProps, <span class="hljs-string">'constructor'</span>)) {
child = protoProps.constructor;
} <span class="hljs-keyword">else</span> {
child = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">()</span> </span>{ <span class="hljs-keyword">return</span> parent.apply(<span class="hljs-keyword">this</span>, <span class="hljs-built_in">arguments</span>); };
}</pre></div></div>
</li>
<li id="section-14">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-14">¶</a>
</div>
<p>Add static properties to the constructor function, if supplied.</p>
</div>
<div class="content"><div class='highlight'><pre> _.extend(child, parent, staticProps);</pre></div></div>
</li>
<li id="section-15">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-15">¶</a>
</div>
<p>Set the prototype chain to inherit from parent,
without calling parent’s constructor function.</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">var</span> Surrogate = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">()</span> </span>{ <span class="hljs-keyword">this</span>.constructor = child; };
Surrogate.prototype = parent.prototype;
child.prototype = <span class="hljs-keyword">new</span> Surrogate();</pre></div></div>
</li>
<li id="section-16">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-16">¶</a>
</div>
<p>Add prototype properties (instance properties)
to the subclass, if supplied.</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">if</span> (protoProps) {
_.extend(child.prototype, protoProps);
}</pre></div></div>
</li>
<li id="section-17">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-17">¶</a>
</div>
<p>Set a convenience property in case the
parent’s prototype is needed later.</p>
</div>
<div class="content"><div class='highlight'><pre> child.__super__ = parent.prototype;
<span class="hljs-keyword">return</span> child;
};</pre></div></div>
</li>
<li id="section-18">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-18">¶</a>
</div>
<h2 id="baseobject">BaseObject</h2>
</div>
</li>
<li id="section-19">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-19">¶</a>
</div>
<p>function for enabling common architectures</p>
</div>
<div class="content"><div class='highlight'><pre>Struck.BaseObject = (<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">()</span> </span>{</pre></div></div>
</li>
<li id="section-20">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-20">¶</a>
</div>
<h4 id="baseobject-constructor">BaseObject Constructor</h4>
</div>
</li>
<li id="section-21">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-21">¶</a>
</div>
<p>constructor is run when object is created
runs base initiation by default</p>
</div>
</li>
<li id="section-22">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-22">¶</a>
</div>
<p><strong>Warning: overwriting the BaseObject
Constructor will disable internal processes.</strong>
In cases where overwriting the constructor
is required call the prototype to preserve
functionality:</p>
</div>
</li>
<li id="section-23">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-23">¶</a>
</div>
<p><code>Struck.BaseObject.prototype.constructor.apply(this, arguments);</code></p>
</div>
<div class="content"><div class='highlight'><pre>
<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">BaseObject</span><span class="hljs-params">(options)</span> </span>{</pre></div></div>
</li>
<li id="section-24">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-24">¶</a>
</div>
<p>run base initiation and provide
hooks that extended objects can use</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">this</span>.initializeObject(options);
<span class="hljs-keyword">this</span>.initialize();
}</pre></div></div>
</li>
<li id="section-25">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-25">¶</a>
</div>
<h5 id="initializeobject">initializeObject</h5>
<p>when the object is created</p>
</div>
<div class="content"><div class='highlight'><pre> BaseObject.prototype.initializeObject = Struck.hook(<span class="hljs-string">'initializeObject'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(options)</span> </span>{</pre></div></div>
</li>
<li id="section-26">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-26">¶</a>
</div>
<p>assign UID to view object</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">this</span>.uid = _.uniqueId(<span class="hljs-string">'uid'</span>);</pre></div></div>
</li>
<li id="section-27">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-27">¶</a>
</div>
<p>add options object to instance</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">this</span>.options = _.extend({}, options);
<span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>;
});</pre></div></div>
</li>
<li id="section-28">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-28">¶</a>
</div>
<h5 id="initialize">initialize</h5>
<p>overwritable function that gets called
when constructing new objects</p>
</div>
<div class="content"><div class='highlight'><pre> BaseObject.prototype.initialize = Struck.hook(<span class="hljs-string">'initialize'</span>, _.noop);</pre></div></div>
</li>
<li id="section-29">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-29">¶</a>
</div>
<h5 id="destroy">destroy</h5>
<p>overwritable function that gets called
when destroying object</p>
</div>
<div class="content"><div class='highlight'><pre> BaseObject.prototype.destroy = Struck.hook(<span class="hljs-string">'destroy'</span>, _.noop);</pre></div></div>
</li>
<li id="section-30">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-30">¶</a>
</div>
<h5 id="hook">hook</h5>
<p>interface for providing method callbacks
like <code>onRender</code></p>
</div>
<div class="content"><div class='highlight'><pre> BaseObject.prototype.hook = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(name, mod)</span> </span>{
<span class="hljs-keyword">var</span> args = _.isUndefined(mod) ? _.rest(<span class="hljs-built_in">arguments</span>) : _.rest(<span class="hljs-built_in">arguments</span>, <span class="hljs-number">2</span>),
prefix = firstDef(mod, <span class="hljs-string">'on'</span>),
methodHook = prefix + capitalize(name);
<span class="hljs-keyword">if</span> (<span class="hljs-keyword">this</span>[methodHook]) {
<span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>[methodHook].apply(<span class="hljs-keyword">this</span>, args);
}
<span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>;
};
<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">reduceProps</span><span class="hljs-params">(self, props)</span> </span>{
<span class="hljs-keyword">return</span> _.reduce(props, <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(memo, prop)</span> </span>{
memo[prop] = self.get(prop);
<span class="hljs-keyword">return</span> memo;
}, {});
}</pre></div></div>
</li>
<li id="section-31">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-31">¶</a>
</div>
<h5 id="get">get</h5>
</div>
<div class="content"><div class='highlight'><pre> BaseObject.prototype.get = Struck.hook(<span class="hljs-string">'get'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(prop)</span> </span>{
<span class="hljs-keyword">var</span> args = _.toArray(<span class="hljs-built_in">arguments</span>);
<span class="hljs-keyword">if</span> (_.isArray(prop)) {
<span class="hljs-keyword">return</span> reduceProps(<span class="hljs-keyword">this</span>, prop);
} <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> (args.length > <span class="hljs-number">1</span>) {
<span class="hljs-keyword">return</span> reduceProps(<span class="hljs-keyword">this</span>, args);
}
<span class="hljs-keyword">return</span> result(<span class="hljs-keyword">this</span>[prop], <span class="hljs-keyword">this</span>);
});</pre></div></div>
</li>
<li id="section-32">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-32">¶</a>
</div>
<h5 id="set">set</h5>
</div>
<div class="content"><div class='highlight'><pre> BaseObject.prototype.set = Struck.hook(<span class="hljs-string">'set'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(prop, val)</span> </span>{
prop = result(prop);
<span class="hljs-keyword">if</span> (_.isObject(prop)) {
_.each(prop, <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(value, property)</span> </span>{
<span class="hljs-keyword">this</span>.set(property, value);
}, <span class="hljs-keyword">this</span>);
}
<span class="hljs-keyword">this</span>[prop] = result(val, <span class="hljs-keyword">this</span>);
<span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>;
});
BaseObject.extend = Struck.extend;</pre></div></div>
</li>
<li id="section-33">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-33">¶</a>
</div>
<h3 id="create">create</h3>
<p>prefered method of creating new objects
over using the <code>new</code> style</p>
</div>
<div class="content"><div class='highlight'><pre> BaseObject.create = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(props, opts)</span> </span>{
<span class="hljs-keyword">var</span> Creator = (!_.isUndefined(props)) ? <span class="hljs-keyword">this</span>.extend(props) : <span class="hljs-keyword">this</span>;
<span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> Creator(_.extend({}, opts));
};
<span class="hljs-keyword">return</span> BaseObject;
})();</pre></div></div>
</li>
<li id="section-34">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-34">¶</a>
</div>
<h2 id="eventobject">EventObject</h2>
</div>
</li>
<li id="section-35">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-35">¶</a>
</div>
<p><code>Struck.EventObject</code> normalizes an event API
for adding event listeners and listening to
objects externally. Using the listen methods
automates undelgating events of view removal.</p>
</div>
<div class="content"><div class='highlight'><pre>Struck.EventObject = (<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">()</span> </span>{
<span class="hljs-pi"> 'use strict'</span>;
<span class="hljs-keyword">var</span> EventObject = Struck.BaseObject.extend();
EventObject.prototype.initializeObject = <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">()</span> </span>{</pre></div></div>
</li>
<li id="section-36">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-36">¶</a>
</div>
<p>all event objects need an intercom for
emiting and listening to events</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">this</span>.com = Struck.Intercom.create();</pre></div></div>
</li>
<li id="section-37">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-37">¶</a>
</div>
<p>call super after defining com which
is used for base hooks</p>
</div>
<div class="content"><div class='highlight'><pre> Struck.BaseObject.prototype.initializeObject.apply(<span class="hljs-keyword">this</span>, <span class="hljs-built_in">arguments</span>);
<span class="hljs-keyword">this</span>.listenedEvents = [];
<span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>;
};</pre></div></div>
</li>
<li id="section-38">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-38">¶</a>
</div>
<h5 id="hook">hook</h5>
</div>
</li>
<li id="section-39">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-39">¶</a>
</div>
<p>trigger intercom events for hook</p>
</div>
<div class="content"><div class='highlight'><pre> EventObject.prototype.hook = <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">(name, mod, args)</span> </span>{
<span class="hljs-keyword">var</span> postfix = <span class="hljs-string">''</span>;
<span class="hljs-keyword">if</span> (mod !== <span class="hljs-literal">undefined</span> && mod !== <span class="hljs-string">'on'</span>) {
postfix = <span class="hljs-string">':'</span> + mod;
}
Struck.BaseObject.prototype.hook.apply(<span class="hljs-keyword">this</span>, <span class="hljs-built_in">arguments</span>);
<span class="hljs-keyword">this</span>.com.emit.apply(<span class="hljs-keyword">this</span>.com, [name + postfix].concat(args));
<span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>;
};</pre></div></div>
</li>
<li id="section-40">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-40">¶</a>
</div>
<h5 id="listento">listenTo</h5>
</div>
</li>
<li id="section-41">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-41">¶</a>
</div>
<p>Registers a event listener to the
appropriate subsystem. Delegates jquery
objects to the jq event system and struck
objects to the instance’s intercom
we then keep a secondary object of events
to remove when the object is deconstructed</p>
</div>
<div class="content"><div class='highlight'><pre> EventObject.prototype.listenTo = <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">(obj, events, func, context)</span> </span>{
<span class="hljs-keyword">var</span> opts = _.chain(<span class="hljs-built_in">arguments</span>).rest(<span class="hljs-number">4</span>).first().value();
addListener(<span class="hljs-keyword">this</span>, {
obj: obj,
events: events,
func: func,
single: firstDef(opts && opts.single, <span class="hljs-literal">false</span>),
context: firstDef(context, <span class="hljs-keyword">this</span>)
});
<span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>;
};</pre></div></div>
</li>
<li id="section-42">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-42">¶</a>
</div>
<h5 id="listenonce">listenOnce</h5>
</div>
<div class="content"><div class='highlight'><pre> EventObject.prototype.listenOnce = <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">(obj, events, func, context)</span> </span>{
<span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>.listenTo(obj, events, func, context, { single: <span class="hljs-literal">true</span> });
};</pre></div></div>
</li>
<li id="section-43">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-43">¶</a>
</div>
<h5 id="stoplistening">stopListening</h5>
<p>removes an event listener from the
appropriate subsystem</p>
</div>
<div class="content"><div class='highlight'><pre> EventObject.prototype.stopListening = <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">(obj, events, func, context)</span> </span>{
removeListener(<span class="hljs-keyword">this</span>, obj, events, func);
<span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>;
};
EventObject.prototype.trigger = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(events)</span> </span>{
<span class="hljs-keyword">this</span>.com.emit.apply(<span class="hljs-keyword">this</span>.com, [events].concat(_.rest(<span class="hljs-built_in">arguments</span>, <span class="hljs-number">1</span>)));
<span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>;
};</pre></div></div>
</li>
<li id="section-44">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-44">¶</a>
</div>
<h5 id="destroy">destroy</h5>
<p>when an object is removed, the destroy function
should be called to remove attached event listeners</p>
</div>
<div class="content"><div class='highlight'><pre> EventObject.prototype.destroy = <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">()</span> </span>{
Struck.BaseObject.prototype.destroy.apply(<span class="hljs-keyword">this</span>, <span class="hljs-built_in">arguments</span>);</pre></div></div>
</li>
<li id="section-45">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-45">¶</a>
</div>
<p>remove all event listeners listeners</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">this</span>.stopListening();
_.defer(<span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(self)</span> </span>{</pre></div></div>
</li>
<li id="section-46">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-46">¶</a>
</div>
<p>destroy com interface</p>
</div>
<div class="content"><div class='highlight'><pre> self.com.destroy();
}, <span class="hljs-keyword">this</span>);
<span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>;
};
<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">addListener</span><span class="hljs-params">(self, opts)</span> </span>{
<span class="hljs-keyword">var</span> obj = opts.obj,
events = splitName(opts.events),
func = opts.func;
<span class="hljs-keyword">var</span> callback = !opts.single ? func : <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">()</span> </span>{
func.apply(<span class="hljs-keyword">this</span>, <span class="hljs-built_in">arguments</span>);
removeListener(self, obj, opts.events, callback);
};
_.each(events, <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(ev)</span> </span>{
self.listenedEvents.push({
events: ev,
func: callback,
obj: obj,
context: opts.context
});
<span class="hljs-keyword">if</span> (obj <span class="hljs-keyword">instanceof</span> jQuery) {
obj[opts.single ? <span class="hljs-string">'one'</span> : <span class="hljs-string">'on'</span>](ev, _.bind(callback, opts.context));
} <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> (obj <span class="hljs-keyword">instanceof</span> Struck.EventObject) {
obj.com[opts.single ? <span class="hljs-string">'once'</span> : <span class="hljs-string">'on'</span>].call(obj.com, ev, callback, opts.context);
}
});
}
<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">removeListener</span><span class="hljs-params">(self, obj, events, func, context)</span> </span>{
events = splitName(events);
<span class="hljs-keyword">var</span> rejects = [],
passes = [];
<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">pushResults</span><span class="hljs-params">(rejected, ev)</span> </span>{
<span class="hljs-keyword">if</span> (rejected) {
rejects.push(ev);
} <span class="hljs-keyword">else</span> {
passes.push(ev);
}
}
_.each(self.listenedEvents, <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(ev)</span> </span>{
_.each(events, <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(name)</span> </span>{
<span class="hljs-keyword">if</span> (func) {
pushResults(ev.obj === obj && ev.events === name && ev.func === func, ev);
} <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> (events) {
pushResults(ev.obj === obj && ev.events === name, ev);
}
});
});
<span class="hljs-keyword">if</span> (!events && !func && obj) {
_.each(self.listenedEvents, <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(ev)</span> </span>{
pushResults(ev.obj === obj, ev);
});
} <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> (!events) {
rejects = self.listenedEvents;
}
self.listenedEvents = passes;
<span class="hljs-built_in">console</span>.log(rejects);
_.each(rejects, <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(reject)</span> </span>{
<span class="hljs-keyword">if</span> (reject.obj <span class="hljs-keyword">instanceof</span> jQuery) {
reject.obj.off(reject.events, _.bind(reject.func, firstDef(context, reject.context)));
} <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> (reject.obj <span class="hljs-keyword">instanceof</span> Struck.EventObject) {
reject.obj.com.off(reject.events, rejects.func);
}
});
}
<span class="hljs-keyword">return</span> EventObject;
})();</pre></div></div>
</li>
<li id="section-47">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-47">¶</a>
</div>
<h2 id="intercom">Intercom</h2>
</div>
</li>
<li id="section-48">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-48">¶</a>
</div>
<p>A standalone function for an event subscriber
system to be used in other modules</p>
</div>
<div class="content"><div class='highlight'><pre>Struck.Intercom = (<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">()</span> </span>{</pre></div></div>
</li>
<li id="section-49">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-49">¶</a>
</div>
<p>setup default subscription object
used to clone and extend in <code>subscribe</code> function</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">var</span> defaultSubscription = {
single: <span class="hljs-literal">false</span>,
name: <span class="hljs-string">'all'</span>,
callback: _.noop,
context: root
};</pre></div></div>
</li>
<li id="section-50">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-50">¶</a>
</div>
<p>get keys from default subscription object
useful for iteration and filtering</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">var</span> subscriptionKeys = _.keys(defaultSubscription);</pre></div></div>
</li>
<li id="section-51">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-51">¶</a>
</div>
<h5 id="constructor">Constructor</h5>
<p>set up default subscriptio object’s context to the
intercom instance and create subscription collection</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">var</span> Intercom = Struck.BaseObject.extend();
Intercom.prototype.initializeObject = <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">()</span> </span>{
Struck.BaseObject.prototype.initializeObject.apply(<span class="hljs-keyword">this</span>, <span class="hljs-built_in">arguments</span>);
<span class="hljs-keyword">this</span>.defaultSubscription = _.extend({}, defaultSubscription, { context: <span class="hljs-keyword">this</span> });
<span class="hljs-keyword">this</span>.subscriptions = [];
<span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>;
};</pre></div></div>
</li>
<li id="section-52">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-52">¶</a>
</div>
<h5 id="intercom-on">Intercom.on</h5>
</div>
<div class="content"><div class='highlight'><pre> Intercom.prototype.on = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(names, callback, context, opts)</span> </span>{
subscriber(<span class="hljs-keyword">this</span>, names, callback, {
single: firstDef(opts && opts.single, <span class="hljs-literal">false</span>),
context: context
});
<span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>;
};</pre></div></div>
</li>
<li id="section-53">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-53">¶</a>
</div>
<h5 id="intercom-once">Intercom.once</h5>
</div>
<div class="content"><div class='highlight'><pre> Intercom.prototype.once = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(names, callback, context)</span> </span>{
<span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>.on(names, callback, context, { single: <span class="hljs-literal">true</span> });
};</pre></div></div>
</li>
<li id="section-54">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-54">¶</a>
</div>
<h5 id="intercom-off">Intercom.off</h5>
</div>
<div class="content"><div class='highlight'><pre> Intercom.prototype.off = <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(names, callback)</span> </span>{
unsubscriber(<span class="hljs-keyword">this</span>, names, callback);
<span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>;
};</pre></div></div>
</li>
<li id="section-55">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-55">¶</a>
</div>
<h5 id="intercom-emit">Intercom.emit</h5>
</div>
<div class="content"><div class='highlight'><pre> Intercom.prototype.emit = <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">(names)</span> </span>{
<span class="hljs-keyword">var</span> args = _.rest(<span class="hljs-built_in">arguments</span>, <span class="hljs-number">1</span>);
<span class="hljs-keyword">var</span> filteredSubs = _.reduce(splitName(names, <span class="hljs-keyword">this</span>), <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">(subs, name)</span> </span>{
<span class="hljs-keyword">var</span> matches = _.filter(<span class="hljs-keyword">this</span>.subscriptions, <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">(subscriber)</span> </span>{
<span class="hljs-keyword">return</span> subscriber.name === name;
}, <span class="hljs-keyword">this</span>);
<span class="hljs-keyword">return</span> subs.concat(matches);
}, [], <span class="hljs-keyword">this</span>);
filteredSubs = _.unique(filteredSubs);
_.each(filteredSubs, <span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-params">(sub)</span> </span>{
trigger(<span class="hljs-keyword">this</span>, sub, args);
}, <span class="hljs-keyword">this</span>);
<span class="hljs-keyword">return</span> <span class="hljs-keyword">this</span>;
};</pre></div></div>
</li>
<li id="section-56">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-56">¶</a>
</div>
<h3 id="private-functions">Private Functions</h3>
</div>
</li>
<li id="section-57">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-57">¶</a>
</div>
<h5 id="subscriber">subscriber</h5>
<p>splits and delegates subscriptions from on/once calls</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">subscriber</span><span class="hljs-params">(com, names, func, opts)</span> </span>{
_.each(splitName(names, com), <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">(name)</span> </span>{
subscribe(com, name, func, {
single: opts.single,
context: opts.context
});
});
}</pre></div></div>
</li>
<li id="section-58">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-58">¶</a>
</div>
<h5 id="subscribe">subscribe</h5>
<p>build subscription object from
name and function, additional
options are optional…</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">subscribe</span><span class="hljs-params">(com, name, func, opts)</span> </span>{
<span class="hljs-keyword">if</span> (!name && !func) { <span class="hljs-keyword">return</span>; }
<span class="hljs-keyword">var</span> subOptions = {
name: name,
callback: func
};</pre></div></div>
</li>
<li id="section-59">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-59">¶</a>
</div>
<p>add useful options to subOptions</p>
</div>
<div class="content"><div class='highlight'><pre> _.each(subscriptionKeys, <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">(key)</span> </span>{
<span class="hljs-keyword">if</span> (opts[key]) {
subOptions[key] = opts[key];
}
});</pre></div></div>
</li>
<li id="section-60">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-60">¶</a>
</div>
<p>create a new subscription from the default object
and overwrite properties with subOptions,
then adds subscription to collection</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">var</span> subscription = _.extend({}, defaultSubscription, subOptions);
com.subscriptions.push(subscription);
}
<span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">unsubscriber</span><span class="hljs-params">(com, names, func)</span> </span>{
<span class="hljs-keyword">if</span> (names === <span class="hljs-literal">undefined</span>) {
unsubscribe(com);
<span class="hljs-keyword">return</span>;
}
_.each(splitName(names, com), <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">(name)</span> </span>{
unsubscribe(com, name, func);
});
}</pre></div></div>
</li>
<li id="section-61">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-61">¶</a>
</div>
<h5 id="unsubscribe">unsubscribe</h5>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">unsubscribe</span><span class="hljs-params">(com, name, func)</span> </span>{
<span class="hljs-keyword">var</span> filter = <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">(sub)</span> </span>{</pre></div></div>
</li>
<li id="section-62">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-62">¶</a>
</div>
<p>com, name, func:
.. remove specific subscriber function</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">if</span> (func) {
<span class="hljs-keyword">return</span> sub.name === name && sub.callback === func;</pre></div></div>
</li>
<li id="section-63">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-63">¶</a>
</div>
<p>com, name:
.. remove all subscribers by name</p>
</div>
<div class="content"><div class='highlight'><pre> } <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> (name) {
<span class="hljs-keyword">return</span> sub.name === name;
}</pre></div></div>
</li>
<li id="section-64">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-64">¶</a>
</div>
<p>remove all subscriptions if no arguments provided</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">return</span> <span class="hljs-literal">true</span>;
};
com.subscriptions = _.reject(com.subscriptions, filter);
}</pre></div></div>
</li>
<li id="section-65">
<div class="annotation">
<div class="pilwrap ">
<a class="pilcrow" href="#section-65">¶</a>
</div>
<h5 id="trigger">trigger</h5>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">trigger</span><span class="hljs-params">(com, sub, args)</span> </span>{
sub.callback.apply(sub.context, args);
<span class="hljs-keyword">if</span> (sub.single) {
unsubscribe(com, sub.name, sub.callback);
}
}
<span class="hljs-keyword">return</span> Intercom;
})();
<span class="hljs-keyword">return</span> Struck;
}));</pre></div></div>
</li>
</ul>
</div>
</body>
</html>