-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
82 lines (69 loc) · 19.3 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
<!DOCTYPE html> <html> <head> <title>jquery.plugin.template.js</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <link rel="stylesheet" media="all" href="docco.css" /> </head> <body> <div id="container"> <div id="background"></div> <table cellpadding="0" cellspacing="0"> <thead> <tr> <th class="docs"> <h1> jquery.plugin.template.js </h1> </th> <th class="code"> </th> </tr> </thead> <tbody> <tr id="section-1"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-1">¶</a> </div> <p><em>jquery.plugin.template.js</em> is an answer to my search for a good generic
template to base all kinds of plugins off of. It is flexible and uses the
latest ideas from Twitter Bootstrap and other places online. One of the
more useful things is the use of jQuery's data API and the calling of
different methods via the plugin after initialization.</p> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-2"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-2">¶</a> </div> <h2>Benefits</h2>
<ul>
<li>your jQuery plugins can be initialized with a settings object <code>{height: 500, width: 300}</code></li>
<li>the user-specified settings override a separate self-referencing default settings object -- a common jQuery plugin best practice</li>
<li>you can call methods on the plugin after initialization, whenever you want</li>
<li>enable binding of events to public methods for clear and readable code</li>
<li>takes best practices from Twitter Bootstrap and others</li>
<li>AMD compatible</li>
</ul> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-3"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-3">¶</a> </div> <h2>Get started</h2>
<ol>
<li>Copy <a href="https://raw.github.com/c4urself/jQuery-Plugin-Template/master/jquery.plugin.template.simple.js">the template</a></li>
<li>Change the name of the plugin ('myplugin')</li>
<li>Add your methods </li>
<li>Joy!</li>
</ol> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-4"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-4">¶</a> </div> <h2>API</h2>
<p><strong>Initialize your plugin</strong></p>
<p><code>
$('.myselector').myplugin({setting1: 'one', setting2: 'two'});
</code></p>
<p><strong>Call a method</strong></p>
<p><code>
$('.myselector').myplugin('mymethod');
</code></p>
<p><strong>Call a method with arguments</strong></p>
<p><code>
$('.myselector').myplugin('mymethod', 'high', 45, false);
</code></p> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-5"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-5">¶</a> </div> <h2>References</h2>
<ul>
<li><a href="http://docs.jquery.com/Plugins/Authoring">jQuery Plugin Authoring</a></li>
<li><a href="https://github.com/twitter/bootstrap/tree/master/js">Twitter Bootstrap Plugins</a></li>
<li><a href="https://github.com/umdjs/umd/blob/master/jqueryPlugin.js">jQuery plugin AMD compatibility</a></li>
</ul> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-6"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-6">¶</a> </div> <p>The constructor for the plugin sets some sensible data, like options and a reference to the element</p> </td> <td class="code"> <div class="highlight"><pre><span class="kd">var</span> <span class="nx">MyPlugin</span> <span class="o">=</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">element</span><span class="p">,</span> <span class="nx">options</span><span class="p">)</span> <span class="p">{</span></pre></div> </td> </tr> <tr id="section-7"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-7">¶</a> </div> <p>Context variable</p> </td> <td class="code"> <div class="highlight"><pre> <span class="kd">var</span> <span class="nx">myplugin</span> <span class="o">=</span> <span class="k">this</span><span class="p">;</span></pre></div> </td> </tr> <tr id="section-8"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-8">¶</a> </div> <p>Set the element as an attribute on the plugin object for future reference.</p> </td> <td class="code"> <div class="highlight"><pre> <span class="k">this</span><span class="p">.</span><span class="nx">$element</span> <span class="o">=</span> <span class="nx">$</span><span class="p">(</span><span class="nx">element</span><span class="p">);</span></pre></div> </td> </tr> <tr id="section-9"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-9">¶</a> </div> <p>Extend the user-defined options with your sensible defaults.</p> </td> <td class="code"> <div class="highlight"><pre> <span class="k">this</span><span class="p">.</span><span class="nx">options</span> <span class="o">=</span> <span class="nx">$</span><span class="p">.</span><span class="nx">extend</span><span class="p">({},</span> <span class="nx">$</span><span class="p">.</span><span class="nx">fn</span><span class="p">.</span><span class="nx">myplugin</span><span class="p">.</span><span class="nx">defaults</span><span class="p">,</span> <span class="nx">options</span><span class="p">);</span></pre></div> </td> </tr> <tr id="section-10"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-10">¶</a> </div> <p>You can extend below here by adding any events you may need to always be available.
Bind any events using an anonymous function to add the context of the
plugin</p> </td> <td class="code"> <div class="highlight"><pre> <span class="k">this</span><span class="p">.</span><span class="nx">$element</span><span class="p">.</span><span class="nx">on</span><span class="p">(</span><span class="s1">'mouseover'</span><span class="p">,</span> <span class="kd">function</span> <span class="p">()</span> <span class="p">{</span><span class="nx">myplugin</span><span class="p">.</span><span class="nx">publicMethod</span><span class="p">();});</span>
<span class="p">};</span>
<span class="nx">MyPlugin</span><span class="p">.</span><span class="nx">prototype</span> <span class="o">=</span> <span class="p">{</span></pre></div> </td> </tr> <tr id="section-11"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-11">¶</a> </div> <p>Have added a few conventions here. You can add attributes, private and public method here. The idea being that you only call methods not starting with underscore (it is not enforced)</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">myAttribute</span><span class="o">:</span> <span class="s1">'value'</span><span class="p">,</span>
<span class="nx">_privateMethod</span><span class="o">:</span> <span class="kd">function</span> <span class="p">()</span> <span class="p">{},</span>
<span class="nx">publicMethod</span><span class="o">:</span> <span class="kd">function</span> <span class="p">()</span> <span class="p">{}</span>
<span class="p">};</span></pre></div> </td> </tr> <tr id="section-12"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-12">¶</a> </div> <p>This self-calling function is used to make the plugin work with either AMD or non-AMD contexts,
it loads a function called <code>factory</code> which takes jQuery as an argument. This makes the plugin
compatible with either AMD or non-AMD loading</p> </td> <td class="code"> <div class="highlight"><pre><span class="p">(</span><span class="kd">function</span> <span class="p">(</span><span class="nx">factory</span><span class="p">)</span> <span class="p">{</span></pre></div> </td> </tr> <tr id="section-13"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-13">¶</a> </div> <p><em>AMD variant</em>. Register as an anonymous module, jQuery will be passed in.</p> </td> <td class="code"> <div class="highlight"><pre> <span class="k">if</span> <span class="p">(</span><span class="k">typeof</span> <span class="nx">define</span> <span class="o">===</span> <span class="s1">'function'</span> <span class="o">&&</span> <span class="nx">define</span><span class="p">.</span><span class="nx">amd</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">define</span><span class="p">([</span><span class="s1">'jquery'</span><span class="p">],</span> <span class="nx">factory</span><span class="p">);</span></pre></div> </td> </tr> <tr id="section-14"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-14">¶</a> </div> <p><em>Browser global variant</em>. jQuery still passed in, not using AMD.</p> </td> <td class="code"> <div class="highlight"><pre> <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
<span class="nx">factory</span><span class="p">(</span><span class="nb">window</span><span class="p">.</span><span class="nx">jQuery</span><span class="p">);</span>
<span class="p">}</span></pre></div> </td> </tr> <tr id="section-15"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-15">¶</a> </div> <p>This is our <code>factory</code> function, basically wrapping the plugin in a function that defines jQuery as <code>$</code></p> </td> <td class="code"> <div class="highlight"><pre><span class="p">}(</span><span class="kd">function</span> <span class="p">(</span><span class="nx">$</span><span class="p">)</span> <span class="p">{</span></pre></div> </td> </tr> <tr id="section-16"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-16">¶</a> </div> <p>This is what jQuery will call</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">$</span><span class="p">.</span><span class="nx">fn</span><span class="p">.</span><span class="nx">myplugin</span> <span class="o">=</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">option</span><span class="p">)</span> <span class="p">{</span></pre></div> </td> </tr> <tr id="section-17"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-17">¶</a> </div> <p>In cases where you want to call a method on your plugin with arguments,
this puts all the arguments except for the method name into an array and sends them along to the function.</p> </td> <td class="code"> <div class="highlight"><pre> <span class="kd">var</span> <span class="nx">args</span> <span class="o">=</span> <span class="p">[].</span><span class="nx">splice</span><span class="p">.</span><span class="nx">call</span><span class="p">(</span><span class="nx">arguments</span><span class="p">,</span> <span class="mi">1</span><span class="p">);</span></pre></div> </td> </tr> <tr id="section-18"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-18">¶</a> </div> <p>Always start out with this.each to be able to cover more than one element</p> </td> <td class="code"> <div class="highlight"><pre> <span class="k">return</span> <span class="k">this</span><span class="p">.</span><span class="nx">each</span><span class="p">(</span><span class="kd">function</span> <span class="p">()</span> <span class="p">{</span>
<span class="kd">var</span> <span class="nx">$this</span> <span class="o">=</span> <span class="nx">$</span><span class="p">(</span><span class="k">this</span><span class="p">),</span></pre></div> </td> </tr> <tr id="section-19"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-19">¶</a> </div> <p>Store per element information using jQuery's data API using the name
of the plugin.</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">data</span> <span class="o">=</span> <span class="nx">$this</span><span class="p">.</span><span class="nx">data</span><span class="p">(</span><span class="s1">'myplugin'</span><span class="p">),</span></pre></div> </td> </tr> <tr id="section-20"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-20">¶</a> </div> <p>Initialization of the plugin should be done with an object</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">options</span> <span class="o">=</span> <span class="k">typeof</span> <span class="nx">option</span> <span class="o">===</span> <span class="s1">'object'</span> <span class="o">&&</span> <span class="nx">option</span><span class="p">;</span></pre></div> </td> </tr> <tr id="section-21"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-21">¶</a> </div> <p><em>Initialization with settings object</em> run initializes a new Plugin object
Each Plugin object receives the element and the options send when initialized,
the data for 'myplugin' is set to the MyPlugin object itself.</p> </td> <td class="code"> <div class="highlight"><pre> <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">data</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">$this</span><span class="p">.</span><span class="nx">data</span><span class="p">(</span><span class="s1">'myplugin'</span><span class="p">,</span> <span class="p">(</span><span class="nx">data</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">MyPlugin</span><span class="p">(</span><span class="k">this</span><span class="p">,</span> <span class="nx">options</span><span class="p">)));</span></pre></div> </td> </tr> <tr id="section-22"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-22">¶</a> </div> <p><em>Method calling with arguments</em>: allow for the calling of methods in the Plugin object
after initialization such that one can do <code>$(".selector").plugin('mymethod')</code>
thereby exposing an easy to use API. Call the method, the args we have extracted
earlier are passed to the called method</p>
<p><strong>Example:</strong>
<code>$('.myselector').myplugin('turnDegrees', 45);</code></p> </td> <td class="code"> <div class="highlight"><pre> <span class="p">}</span> <span class="k">else</span> <span class="k">if</span> <span class="p">(</span><span class="k">typeof</span> <span class="nx">option</span> <span class="o">===</span> <span class="s1">'string'</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">data</span><span class="p">[</span><span class="nx">option</span><span class="p">].</span><span class="nx">apply</span><span class="p">(</span><span class="nx">data</span><span class="p">,</span> <span class="nx">args</span><span class="p">);</span>
<span class="p">}</span>
<span class="p">});</span>
<span class="p">};</span></pre></div> </td> </tr> <tr id="section-23"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-23">¶</a> </div> <p>Use a separate and easy to understand options dictionary for default
settings. Users can refer to these to understand the plugin.</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">$</span><span class="p">.</span><span class="nx">fn</span><span class="p">.</span><span class="nx">myplugin</span><span class="p">.</span><span class="nx">defaults</span> <span class="o">=</span> <span class="p">{</span>
<span class="nx">width</span><span class="o">:</span> <span class="mi">500000</span><span class="p">,</span>
<span class="nx">text</span><span class="o">:</span> <span class="s1">'Crazy man'</span>
<span class="p">};</span>
<span class="p">}));</span>
</pre></div> </td> </tr> </tbody> </table> </div> </body> </html>