jQuery.widget.bridge.html
7.82 KB
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
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>jQuery UI jQuery documentation</title>
<style>
body {
font-family: "Trebuchet MS", "Arial", "Helvetica", "Verdana", "sans-serif"
}
.gutter {
display: none;
}
</style>
</head>
<body>
<script>{
"title":
"Widget Plugin Bridge",
"excerpt":
"Part of the jQuery Widget Factory is the jQuery.widget.bridge() method. This acts as the middleman between the object created by $.widget() and the jQuery API.",
"termSlugs": {
"category": [
"utilities","widgets"
]
}
}</script><article id="jQuery-widget-bridge1" class="entry method"><h2 class="section-title"><span class="name">jQuery.widget.bridge( name, constructor )</span></h2>
<div class="entry-wrapper">
<p class="desc"><strong>Description: </strong>Part of the <a href="/jQuery.widget/">jQuery Widget Factory</a> is the <code>jQuery.widget.bridge()</code> method. This acts as the middleman between the object created by <code>$.widget()</code> and the jQuery API.</p>
<ul class="signatures"><li class="signature">
<h4 class="name"><a id="jQuery-widget-bridge-name-constructor" href="#jQuery-widget-bridge-name-constructor"><span class="icon-link"></span>jQuery.widget.bridge( name, constructor )</a></h4>
<ul>
<li>
<div><strong>name</strong></div>
<div>Type: <a href="http://api.jquery.com/Types/#String">String</a>
</div>
<div>The name of the plugin to create.</div>
</li>
<li>
<div><strong>constructor</strong></div>
<div>Type: <a href="http://api.jquery.com/Types/#Function">Function</a>()</div>
<div>The object to instantiate when the plugin is invoked.</div>
</li>
</ul>
</li></ul>
<div class="longdesc" id="entry-longdesc">
<p><code>$.widget.bridge()</code> does a few things:</p>
<ul>
<li>Connects a regular JavaScript constructor to the jQuery API.</li>
<li>Automatically creates instances of said object and stores it within the element's <code>$.data</code> cache.</li>
<li>Allows calls to public methods.</li>
<li>Prevents calls to private methods.</li>
<li>Prevents method calls on uninitialized objects.</li>
<li>Protects against multiple initializations.</li>
</ul>
<p>jQuery UI widgets are created using <code>$.widget( "foo.bar", {} );</code> syntax to define an object from which instances will be created. Given a DOM structure with five <code>.foo</code>'s, <code>$( ".foo" ).bar();</code> will create five instances of your "bar" object. <code>$.widget.bridge()</code> works inside the factory by taking your base "bar" object and giving it a public API. Therefore, you can create instances by writing <code>$( ".foo" ).bar()</code>, and call methods by writing <code>$( ".foo" ).bar( "baz" )</code>.</p>
<p>If all you want is one-time initialization and calling methods, your object passed to <code>jQuery.widget.bridge()</code> can be very minimal:</p>
<div class="syntaxhighlighter javascript nogutter">
<table>
<tbody>
<tr>
<td class="gutter">
<div class="line n1">1</div>
<div class="line n2">2</div>
<div class="line n3">3</div>
<div class="line n4">4</div>
<div class="line n5">5</div>
<div class="line n6">6</div>
<div class="line n7">7</div>
<div class="line n8">8</div>
<div class="line n9">9</div>
<div class="line n10">10</div>
<div class="line n11">11</div>
<div class="line n12">12</div>
<div class="line n13">13</div>
</td>
<td class="code">
<pre><div class="container"><div class="line"><code><span class="keyword">var</span> Highlighter = <span class="keyword">function</span>( options, element ) {</code></div></div><div class="container"><div class="line"><code> <span class="keyword">this</span>.options = options;</code></div></div><div class="container"><div class="line"><code> <span class="keyword">this</span>.element = $( element );</code></div></div><div class="container"><div class="line"><code> <span class="keyword">this</span>._set( <span class="number">800</span> );</code></div></div><div class="container"><div class="line"><code>};</code></div></div><div class="container"><div class="line"><code>Highlighter.prototype = {</code></div></div><div class="container"><div class="line"><code> toggle: <span class="keyword">function</span>() {</code></div></div><div class="container"><div class="line"><code> <span class="keyword">this</span>._set( <span class="keyword">this</span>.element.css( <span class="string">"font-weight"</span>) === <span class="number">400</span> ? <span class="number">800</span> : <span class="number">400</span> );</code></div></div><div class="container"><div class="line"><code> },</code></div></div><div class="container"><div class="line"><code> _set: <span class="keyword">function</span>(value) {</code></div></div><div class="container"><div class="line"><code> <span class="keyword">this</span>.element.css( <span class="string">"font-weight"</span>, value );</code></div></div><div class="container"><div class="line"><code> }</code></div></div><div class="container"><div class="line"><code>};</code></div></div></pre>
</td>
</tr>
</tbody>
</table>
</div>
<p>All you need here is a function that acts as the constructor, accepting two arguments:</p>
<ul>
<li>
<code>options</code>: an object of configuration options</li>
<li>
<code>element</code>: the DOM element this instance was created on</li>
</ul>
<p>You can then hook this object up as a jQuery plugin using the bridge and use it on any jQuery object:</p>
<div class="syntaxhighlighter javascript nogutter">
<table>
<tbody>
<tr>
<td class="gutter">
<div class="line n1">1</div>
<div class="line n2">2</div>
<div class="line n3">3</div>
<div class="line n4">4</div>
<div class="line n5">5</div>
<div class="line n6">6</div>
<div class="line n7">7</div>
<div class="line n8">8</div>
</td>
<td class="code">
<pre><div class="container"><div class="line"><code><span class="comment">// Hook up the plugin</span></code></div></div><div class="container"><div class="line"><code>$.widget.bridge( <span class="string">"colorToggle"</span>, Highlighter );</code></div></div><div class="container"><div class="line"><code> </code></div></div><div class="container"><div class="line"><code><span class="comment">// Initialize it on divs</span></code></div></div><div class="container"><div class="line"><code>$( <span class="string">"div"</span> ).colorToggle().click(<span class="keyword">function</span>() {</code></div></div><div class="container"><div class="line"><code> <span class="comment">// Call the public method on click</span></code></div></div><div class="container"><div class="line"><code> $( <span class="keyword">this</span> ).colorToggle( <span class="string">"toggle"</span> );</code></div></div><div class="container"><div class="line"><code>});</code></div></div></pre>
</td>
</tr>
</tbody>
</table>
</div>
<p>To use all the features of the bridge, your object also needs to have an <code>_init()</code> method on the prototype. This will get called whenever the plugin is invoked while an instance already exists. In that case you also need to have an <code>option()</code> method. This will be invoked with the options as the first argument. If there were none, the argument will be an empty object. For a proper implementation of the <code>option</code> method, check out the implementation of <a href="/jQuery.widget/#jQuery-Widget2"><code>$.Widget</code></a>.</p>
<p>There is one optional property the bridge will use, if present: If your object's prototype has a <code>widgetFullName</code> property, this will be used as the key for storing and retrieving the instance. Otherwise, the name argument will be used.</p>
</div>
</div></article>
</body>
</html>