|
|
<!DOCTYPE html>
<html><head> <title>Semantic Modules</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="section-1"> <div class="annotation"> <div class="pilwrap for-h1"> <a class="pilcrow" href="#section-1">¶</a> </div> <h1>Semantic Modules</h1><p>This particular pattern is useful for describing a group of elements which share behavior, for example a modal or a popup.The module is made up of three parts: <em>a group definition</em>, <em>a singular definition</em>, and a <em>settings object</em>.</p><p>Semantic is unique in that all arbitrary data is a setting. Semantic modules also are self documenting, with module.debug calls serving to explain state, and log performance data.<a href="#">Read more about coding conventions</a></p>
</div> <div class="content"><div class='highlight'><pre><span class="comment">/* * # Semantic Module 1.0 * http://github.com/quirkyinc/semantic * * * Copyright 2013 Contributors * Released under the MIT license * http://jquery.org/license * * Released: April 17 2013 */</span>
;(<span class="function"><span class="keyword">function</span> <span class="params">( $, window, document, undefined )</span> {</span>
$.fn.example = <span class="keyword">function</span>(parameters) {</pre></div></div> </li> <li id="section-2"> <div class="annotation"> <div class="pilwrap for-h2"> <a class="pilcrow" href="#section-2">¶</a> </div> <h2>Group</h2><p>Some properties remain constant across all instances of a module.</p>
</div> <div class="content"><div class='highlight'><pre> <span class="keyword">var</span></pre></div></div> </li> <li id="section-3"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-3">¶</a> </div> <p>Store a reference to the module group, this can be useful to refer to other modules inside each module</p>
</div> <div class="content"><div class='highlight'><pre> $allModules = $(<span class="keyword">this</span>),</pre></div></div> </li> <li id="section-4"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-4">¶</a> </div> <p>Extend settings to merge run-time settings with defaults</p>
</div> <div class="content"><div class='highlight'><pre> settings = $.extend(<span class="literal">true</span>, {}, $.fn.example.settings, parameters),</pre></div></div> </li> <li id="section-5"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-5">¶</a> </div> <p>Define namespaces for storing module instance and binding events</p>
</div> <div class="content"><div class='highlight'><pre> eventNamespace = <span class="string">'.'</span> + settings.namespace, moduleNamespace = <span class="string">'module-'</span> + settings.namespace,</pre></div></div> </li> <li id="section-6"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-6">¶</a> </div> <p>Preserve selector from outside each scope and mark current time for performance tracking</p>
</div> <div class="content"><div class='highlight'><pre> selector = $allModules.selector || <span class="string">''</span>, time = <span class="keyword">new</span> Date().getTime(), performance = [],</pre></div></div> </li> <li id="section-7"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-7">¶</a> </div> <p>Preserve original arguments to determine if a method is being invoked</p>
</div> <div class="content"><div class='highlight'><pre> query = arguments[<span class="number">0</span>], methodInvoked = (<span class="keyword">typeof</span> query == <span class="string">'string'</span>), queryArguments = [].slice.call(arguments, <span class="number">1</span>), invokedResponse ;</pre></div></div> </li> <li id="section-8"> <div class="annotation"> <div class="pilwrap for-h2"> <a class="pilcrow" href="#section-8">¶</a> </div> <h2>Singular</h2><p>Iterate over all elements to initialize module</p>
</div> <div class="content"><div class='highlight'><pre> $allModules .each(<span class="keyword">function</span>() { <span class="keyword">var</span></pre></div></div> </li> <li id="section-9"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-9">¶</a> </div> <p>Cache selectors using selector definitions for access inside instance of module</p>
</div> <div class="content"><div class='highlight'><pre> $module = $(<span class="keyword">this</span>), $text = $module.find(settings.selector.text),</pre></div></div> </li> <li id="section-10"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-10">¶</a> </div> <p>Define private variables which can be used to maintain internal state, these cannot be changed from outside the module closure so use conservatively</p>
</div> <div class="content"><div class='highlight'><pre> foo = <span class="literal">false</span>,</pre></div></div> </li> <li id="section-11"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-11">¶</a> </div> <p>Define variables used to track module state. Default values are set using <code>a || b</code> syntax</p>
</div> <div class="content"><div class='highlight'><pre> instance = $module.data(moduleNamespace), element = <span class="keyword">this</span>,</pre></div></div> </li> <li id="section-12"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-12">¶</a> </div> <p>Alias settings object for convenience and performance</p>
</div> <div class="content"><div class='highlight'><pre> namespace = settings.namespace, error = settings.error, className = settings.className,</pre></div></div> </li> <li id="section-13"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-13">¶</a> </div> <p>You may also find it useful to alias your own settings</p>
</div> <div class="content"><div class='highlight'><pre> text = settings.text,
module ;</pre></div></div> </li> <li id="section-14"> <div class="annotation"> <div class="pilwrap for-h2"> <a class="pilcrow" href="#section-14">¶</a> </div> <h2>Module Behavior</h2>
</div> <div class="content"><div class='highlight'><pre> module = {</pre></div></div> </li> <li id="section-15"> <div class="annotation"> <div class="pilwrap for-h3"> <a class="pilcrow" href="#section-15">¶</a> </div> <h3>Required</h3><h4>Initialize</h4><p>Initialize attaches events and preserves each instance in html metadata</p>
</div> <div class="content"><div class='highlight'><pre> initialize: <span class="keyword">function</span>() { module.verbose(<span class="string">'Initializing module for'</span>, element); $module .on(<span class="string">'click'</span> + eventNamespace, module.exampleBehavior) ;</pre></div></div> </li> <li id="section-16"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-16">¶</a> </div> <p>The instance is just a copy of the module definition, we store it in metadata so we can use it outside of scope, but also define it for immediate use</p>
</div> <div class="content"><div class='highlight'><pre> instance = module; $module .data(moduleNamespace, instance) ; },</pre></div></div> </li> <li id="section-17"> <div class="annotation"> <div class="pilwrap for-h4"> <a class="pilcrow" href="#section-17">¶</a> </div> <h4>Destroy</h4><p>Removes all events and the instance copy from metadata</p>
</div> <div class="content"><div class='highlight'><pre> destroy: <span class="keyword">function</span>() { module.verbose(<span class="string">'Destroying previous module for'</span>, element); $module .removeData(moduleNamespace) .off(eventNamespace) ; },</pre></div></div> </li> <li id="section-18"> <div class="annotation"> <div class="pilwrap for-h4"> <a class="pilcrow" href="#section-18">¶</a> </div> <h4>Refresh</h4><p>Selectors are cached so we sometimes need to manually refresh the cache</p>
</div> <div class="content"><div class='highlight'><pre> refresh: <span class="keyword">function</span>() { module.verbose(<span class="string">'Refreshing selector cache for'</span>, element); $module = $(element); $text = $(<span class="keyword">this</span>).find(settings.selector.text); },</pre></div></div> </li> <li id="section-19"> <div class="annotation"> <div class="pilwrap for-h3"> <a class="pilcrow" href="#section-19">¶</a> </div> <h3>Custom</h3><h4>By Event</h4><p>Sometimes it makes sense to call an event handler by its type if it is dependent on the event to behave properly</p>
</div> <div class="content"><div class='highlight'><pre> event: { click: <span class="keyword">function</span>(event) { module.verbose(<span class="string">'Preventing default action'</span>); <span class="keyword">if</span>( !$module.hasClass(className.disabled) ) { module.behavior(); } event.preventDefault(); } },</pre></div></div> </li> <li id="section-20"> <div class="annotation"> <div class="pilwrap for-h4"> <a class="pilcrow" href="#section-20">¶</a> </div> <h4>By Function</h4><p>Other times events make more sense for methods to be called by their function if it is ambivalent to how it is invoked</p>
</div> <div class="content"><div class='highlight'><pre> behavior: <span class="keyword">function</span>() { module.debug(<span class="string">'Changing the text to a new value'</span>, text); <span class="keyword">if</span>( !module.has.text() ) { module.set.text( text); } },</pre></div></div> </li> <li id="section-21"> <div class="annotation"> <div class="pilwrap for-h4"> <a class="pilcrow" href="#section-21">¶</a> </div> <h4>Vocabulary</h4><p>Custom methods should be defined with consistent vocabulary some useful terms: "has", "set", "get", "change", "add", "remove"</p><p>This makes it easier for new developers to get to know your module without learning your schema</p>
</div> <div class="content"><div class='highlight'><pre> has: { text: <span class="keyword">function</span>(state) { module.verbose(<span class="string">'Checking whether text state exists'</span>, state); <span class="keyword">if</span>( text[state] === <span class="literal">undefined</span> ) { module.error(error.noText); <span class="keyword">return</span> <span class="literal">false</span>; } <span class="keyword">return</span> <span class="literal">true</span>; } },
set: { text: <span class="keyword">function</span>(state) { module.verbose(<span class="string">'Setting text to new state'</span>, state); <span class="keyword">if</span>( module.has.text(state) ) { $text .text( text[state] ) ; settings.onChange(); } } },</pre></div></div> </li> <li id="section-22"> <div class="annotation"> <div class="pilwrap for-h3"> <a class="pilcrow" href="#section-22">¶</a> </div> <h3>Standard</h3><h4>Setting</h4><p>Module settings can be read or set using this method</p><p>Settings can either be specified by modifying the module defaults, by initializing the module with a settings object, or by changing a setting by invoking this method<code>$(.foo').example('setting', 'moduleName');</code></p>
</div> <div class="content"><div class='highlight'><pre> setting: <span class="keyword">function</span>(name, value) { <span class="keyword">if</span>(value !== <span class="literal">undefined</span>) { <span class="keyword">if</span>( $.isPlainObject(name) ) { $.extend(<span class="literal">true</span>, settings, name); } <span class="keyword">else</span> { settings[name] = value; } } <span class="keyword">else</span> { <span class="keyword">return</span> settings[name]; } },</pre></div></div> </li> <li id="section-23"> <div class="annotation"> <div class="pilwrap for-h4"> <a class="pilcrow" href="#section-23">¶</a> </div> <h4>Internal</h4><p>Module internals can be set or retrieved as well<code>$(.foo').example('internal', 'behavior', function() { // do something });</code></p>
</div> <div class="content"><div class='highlight'><pre> internal: <span class="keyword">function</span>(name, value) { <span class="keyword">if</span>(value !== <span class="literal">undefined</span>) { <span class="keyword">if</span>( $.isPlainObject(name) ) { $.extend(<span class="literal">true</span>, module, name); } <span class="keyword">else</span> { module[name] = value; } } <span class="keyword">else</span> { <span class="keyword">return</span> module[name]; } },</pre></div></div> </li> <li id="section-24"> <div class="annotation"> <div class="pilwrap for-h4"> <a class="pilcrow" href="#section-24">¶</a> </div> <h4>Debug</h4><p>Debug pushes arguments to the console formatted as a debug statement</p>
</div> <div class="content"><div class='highlight'><pre> debug: <span class="keyword">function</span>() { <span class="keyword">if</span>(settings.debug) { module.performance.log(arguments[<span class="number">0</span>]); module.verbose = Function.prototype.bind.call(console.info, console, settings.moduleName + <span class="string">':'</span>); } },</pre></div></div> </li> <li id="section-25"> <div class="annotation"> <div class="pilwrap for-h4"> <a class="pilcrow" href="#section-25">¶</a> </div> <h4>Verbose</h4><p>Calling verbose internally allows for additional data to be logged which can assist in debugging</p>
</div> <div class="content"><div class='highlight'><pre> verbose: <span class="keyword">function</span>() { <span class="keyword">if</span>(settings.verbose && settings.debug) { module.performance.log(arguments[<span class="number">0</span>]); module.verbose = Function.prototype.bind.call(console.info, console, settings.moduleName + <span class="string">':'</span>); } },</pre></div></div> </li> <li id="section-26"> <div class="annotation"> <div class="pilwrap for-h4"> <a class="pilcrow" href="#section-26">¶</a> </div> <h4>Error</h4><p>Error allows for the module to report named error messages, it may be useful to modify this to push error messages to the user. Error messages are defined in the modules settings object.</p>
</div> <div class="content"><div class='highlight'><pre> error: <span class="keyword">function</span>() { <span class="keyword">if</span>(console.log !== <span class="literal">undefined</span>) { module.error = Function.prototype.bind.call(console.log, console, settings.moduleName + <span class="string">':'</span>); } },</pre></div></div> </li> <li id="section-27"> <div class="annotation"> <div class="pilwrap for-h4"> <a class="pilcrow" href="#section-27">¶</a> </div> <h4>Performance</h4><p>This is called on each debug statement and logs the time since the last debug statement.</p>
</div> <div class="content"><div class='highlight'><pre> performance: { log: <span class="keyword">function</span>(message) { <span class="keyword">var</span> currentTime, executionTime ; <span class="keyword">if</span>(settings.performance) { currentTime = <span class="keyword">new</span> Date().getTime(); executionTime = currentTime - time; time = currentTime; performance.push({ <span class="string">'Name'</span> : message, <span class="string">'Execution Time'</span> : executionTime }); clearTimeout(module.performance.timer); module.performance.timer = setTimeout(module.performance.display, <span class="number">500</span>); } },</pre></div></div> </li> <li id="section-28"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-28">¶</a> </div> <p>Performance data is assumed to be complete 500ms after the last log message receieved</p>
</div> <div class="content"><div class='highlight'><pre> display: <span class="keyword">function</span>() { <span class="keyword">var</span> title = settings.moduleName + <span class="string">' Performance ('</span> + selector + <span class="string">')'</span>, caption = settings.moduleName + <span class="string">': '</span> + selector + <span class="string">'('</span> + $allModules.size() + <span class="string">' elements)'</span> ; <span class="keyword">if</span>(console.group !== <span class="literal">undefined</span> && performance.length > <span class="number">0</span>) { console.groupCollapsed(title); <span class="keyword">if</span>(console.table) { console.table(performance); } <span class="keyword">else</span> { $.each(performance, <span class="keyword">function</span>(index, data) { console.log(data[<span class="string">'Name'</span>] + <span class="string">':'</span> + data[<span class="string">'Execution Time'</span>]); }); } console.groupEnd(); performance = []; } } },</pre></div></div> </li> <li id="section-29"> <div class="annotation"> <div class="pilwrap for-h4"> <a class="pilcrow" href="#section-29">¶</a> </div> <h4>Invoke</h4><p>Invoke is used to lookup and invoke a method or property by a dot notation string definition, for example<code>$('.foo').example('invoke', 'set.text', 'Foo')</code></p>
</div> <div class="content"><div class='highlight'><pre> invoke: <span class="keyword">function</span>(query, passedArguments, context) { <span class="keyword">var</span> maxDepth, found ; passedArguments = passedArguments || queryArguments; context = element || context; <span class="keyword">if</span>(<span class="keyword">typeof</span> query == <span class="string">'string'</span> && instance !== <span class="literal">undefined</span>) { query = query.split(<span class="string">'.'</span>); maxDepth = query.length - <span class="number">1</span>; $.each(query, <span class="keyword">function</span>(depth, value) { <span class="keyword">if</span>( $.isPlainObject( instance[value] ) && (depth != maxDepth) ) { instance = instance[value]; <span class="keyword">return</span> <span class="literal">true</span>; } <span class="keyword">else</span> <span class="keyword">if</span>( instance[value] !== <span class="literal">undefined</span> ) { found = instance[value]; <span class="keyword">return</span> <span class="literal">true</span>; } module.error(error.method); <span class="keyword">return</span> <span class="literal">false</span>; }); } <span class="keyword">if</span> ( $.isFunction( found ) ) { module.verbose(<span class="string">'Executing invoked function'</span>, found); <span class="keyword">return</span> found.apply(context, passedArguments); } <span class="keyword">return</span> found || <span class="literal">false</span>; } };</pre></div></div> </li> <li id="section-30"> <div class="annotation"> <div class="pilwrap for-h3"> <a class="pilcrow" href="#section-30">¶</a> </div> <h3>Determining Intent</h3><p>Invoking a method directly $('.foo').module('set.text', 'Ho hum');The module checks to see if you passed in a method name to call</p>
</div> <div class="content"><div class='highlight'><pre> <span class="keyword">if</span>(methodInvoked) { <span class="keyword">if</span>(instance === <span class="literal">undefined</span>) { module.initialize(); } invokedResponse = module.invoke(query); }</pre></div></div> </li> <li id="section-31"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-31">¶</a> </div> <p>If you didn't pass in anything it can assume you are initializing the module</p>
</div> <div class="content"><div class='highlight'><pre> <span class="keyword">else</span> { <span class="keyword">if</span>(instance !== <span class="literal">undefined</span>) { module.destroy(); } module.initialize(); } }) ;</pre></div></div> </li> <li id="section-32"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-32">¶</a> </div> <p>If you called invoke, you may have a returned value which shoudl be returned, otherwise allow the call to chain</p>
</div> <div class="content"><div class='highlight'><pre> <span class="keyword">return</span> (invokedResponse) ? invokedResponse : <span class="keyword">this</span> ;};</pre></div></div> </li> <li id="section-33"> <div class="annotation"> <div class="pilwrap for-h2"> <a class="pilcrow" href="#section-33">¶</a> </div> <h2>Settings</h2><p>It is necessary to include a settings object which specifies the defaults for your module</p>
</div> <div class="content"><div class='highlight'><pre>$.fn.example.settings = {</pre></div></div> </li> <li id="section-34"> <div class="annotation"> <div class="pilwrap for-h3"> <a class="pilcrow" href="#section-34">¶</a> </div> <h3>Required</h3><p>Used in debug statements to refer to the module itself</p>
</div> <div class="content"><div class='highlight'><pre> moduleName : <span class="string">'Todo Module'</span>,</pre></div></div> </li> <li id="section-35"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-35">¶</a> </div> <p>Whether debug content should be outputted to console</p>
</div> <div class="content"><div class='highlight'><pre> debug : <span class="literal">true</span>,</pre></div></div> </li> <li id="section-36"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-36">¶</a> </div> <p>Whether extra debug content should be outputted</p>
</div> <div class="content"><div class='highlight'><pre> verbose : <span class="literal">true</span>,</pre></div></div> </li> <li id="section-37"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-37">¶</a> </div> <p>Whether to track performance data</p>
</div> <div class="content"><div class='highlight'><pre> performance : <span class="literal">true</span>,</pre></div></div> </li> <li id="section-38"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-38">¶</a> </div> <p>A unique identifier used to namespace events,and preserve the module instance</p>
</div> <div class="content"><div class='highlight'><pre> namespace : <span class="string">'example'</span>,</pre></div></div> </li> <li id="section-39"> <div class="annotation"> <div class="pilwrap for-h3"> <a class="pilcrow" href="#section-39">¶</a> </div> <h3>Optional</h3><p>Selectors used by your module</p>
</div> <div class="content"><div class='highlight'><pre> selector : { example : <span class="string">'.example'</span> },</pre></div></div> </li> <li id="section-40"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-40">¶</a> </div> <p>Error messages returned by the module</p>
</div> <div class="content"><div class='highlight'><pre> error: { noText : <span class="string">'The text you tried to display has not been defined.'</span>, method : <span class="string">'The method you called is not defined.'</span> },</pre></div></div> </li> <li id="section-41"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-41">¶</a> </div> <p>Class names which your module refers to</p>
</div> <div class="content"><div class='highlight'><pre> className : { disabled : <span class="string">'disabled'</span> },</pre></div></div> </li> <li id="section-42"> <div class="annotation"> <div class="pilwrap "> <a class="pilcrow" href="#section-42">¶</a> </div> <p>Metadata stored or retrieved by your module. <code>$('.foo').data('value');</code></p>
</div> <div class="content"><div class='highlight'><pre> metadata: { notUsed: <span class="string">'notUsed'</span> },</pre></div></div> </li> <li id="section-43"> <div class="annotation"> <div class="pilwrap for-h3"> <a class="pilcrow" href="#section-43">¶</a> </div> <h3>Callbacks</h3><p>Callbacks are often useful to include in your settings object</p>
</div> <div class="content"><div class='highlight'><pre> onChange : <span class="keyword">function</span>() {},</pre></div></div> </li> <li id="section-44"> <div class="annotation"> <div class="pilwrap for-h3"> <a class="pilcrow" href="#section-44">¶</a> </div> <h3>Definition Specific</h3><p>You may also want to include settings specific to your module's function</p>
</div> <div class="content"><div class='highlight'><pre> text: { hover : <span class="string">'You are hovering me now'</span>, click : <span class="string">'You clicked on me'</span> }
};
})( jQuery, window , document );</pre></div></div> </li> </ul> </div></body></html>
|
