← Back to branch summary

~ubuntu-branches/ubuntu/raring/maas/raring-updates

« back to all changes in this revision

Viewing changes to src/maasserver/static/jslibs/yui/3.4.1/docs/plugin/index.html

  • Committer: Package Import Robot
  • Author(s): Andres Rodriguez
  • Date: 2012-07-03 17:42:37 UTC
  • mfrom: (1.1.13)
  • Revision ID: package-import@ubuntu.com-20120703174237-p8l0keuuznfg721k
Tags: 0.1+bzr709+dfsg-0ubuntu1
* New Upstream release
* debian/control:
  - Depends on python-celery, python-tempita, libjs-yui3-{full,min},
    libjs-raphael
* debian/maas.install:
  - Install apiclient, celeryconfig.py, maas-import-pxe-files, preseeds_v2.
  - Update to install various files from chroot, rather tha manually copy
    them from the source.
* debian/maas.links: symlink celeryconfig.py
* debian/maas.maas-celery.upstart: Add job.
* debian/rules:
  - Install celery upstart job.
  - Do not install jslibs as packages are now used.
  - Drop copying of maas_local_settings_sample.py as source now ships
    a maas_local_settings.py
* debian/patches:
  - 04-maas-http-fix.patch: Drop. Merged upstream.
  - 01-fix-database-settings.patch: Refreshed.
  - 99_enums_js.patch: Added until creation of enum.js / build process
    is fixed.
* debian/maas.postinst: Update bzr version to correctly handle upgrades.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/maasserver/static/jslibs/yui/3.4.1/docs/plugin/index.html
1
 
<!DOCTYPE html>
2
 
<html lang="en">
3
 
<head>
4
 
    <meta charset="utf-8">
5
 
    <title>Plugin</title>
6
 
    <link rel="stylesheet" href="http://yui.yahooapis.com/3.4.0pr3/build/cssgrids/grids-min.css">
7
 
    <link rel="stylesheet" href="../assets/css/main.css">
8
 
    <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
9
 
    <script src="../../build/yui/yui-min.js"></script>
10
 
</head>
11
 
<body>
12
 
 
13
 
<div id="doc">
14
 
    <h1>Plugin</h1>
15
 
 
16
 
    
17
 
        <a href="#toc" class="jump">Jump to Table of Contents</a>
18
 
    
19
 
 
20
 
    <div class="yui3-g">
21
 
        <div id="main" class="yui3-u">
22
 
            <div class="content"><div class="intro">
23
 
    <p>
24
 
    Plugins allow you to unobtrusively add functionality to objects (referred to as the "host" object) such as nodes and widgets. 
25
 
    Plugins can inherit from the <code>Plugin.Base</code> class, but this is not a hard requirement as we'll see later.
26
 
    </p>
27
 
 
28
 
    <p>
29
 
    Plugins are used to add atomic pieces of functionality or features to component instances (hosts), without having  to bake support or even 
30
 
    knowledge of the feature into the component class. This allows features to be mixed and matched per component instance, without having to build all 
31
 
    features into a monolithic component class or having to ship multiple versions of the component class with varying combinations of features.
32
 
    </p>
33
 
</div>
34
 
 
35
 
<h2 id="getting-started">Getting Started</h2>
36
 
 
37
 
<p>
38
 
To include the source files for Plugin and its dependencies, first load
39
 
the YUI seed file if you haven't already loaded it.
40
 
</p>
41
 
 
42
 
<pre class="code prettyprint">&lt;script src=&quot;http:&#x2F;&#x2F;yui.yahooapis.com&#x2F;3.4.1&#x2F;build&#x2F;yui&#x2F;yui-min.js&quot;&gt;&lt;&#x2F;script&gt;</pre>
43
 
 
44
 
 
45
 
<p>
46
 
Next, create a new YUI instance for your application and populate it with the
47
 
modules you need by specifying them as arguments to the <code>YUI().use()</code> method.
48
 
YUI will automatically load any dependencies required by the modules you
49
 
specify.
50
 
</p>
51
 
 
52
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a new YUI instance and populate it with the required modules.
53
 
YUI().use(&#x27;plugin&#x27;, function (Y) {
54
 
    &#x2F;&#x2F; Plugin is available and ready for use. Add implementation
55
 
    &#x2F;&#x2F; code here.
56
 
});</pre>
57
 
 
58
 
 
59
 
<p>
60
 
For more information on creating YUI instances and on the
61
 
<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the
62
 
documentation for the <a href="../yui/index.html">YUI Global object</a>.
63
 
</p>
64
 
 
65
 
 
66
 
<h2 id="using">Creating Plugins</h2>
67
 
 
68
 
<h3 id="simple">Simple Plugins</h3>
69
 
 
70
 
<p>
71
 
For the most basic plugins, which don't have any events or attributes of their own, and which don't modify the behavior
72
 
of the host by listening for any host events, or overriding any of the host's methods, plugins can simply be basic JavaScript classes.
73
 
</p>
74
 
 
75
 
<p>
76
 
The only requirement for the class is that it has a static namespace property <code>NS</code> with a value assigned to it. 
77
 
The value of the <code>NS</code> property is used to define the property on the host instance which will refer to 
78
 
the plugin when it's plugged into the host.
79
 
</p>
80
 
 
81
 
<p>
82
 
When plugins are plugged into a host instance a new instance of the plugin is created, 
83
 
and a reference to the host is added to the configuration object passed to the plugin's constructor, 
84
 
so that the plugin has a way to reference the host object. (similarly, when plugins are unplugged from a host 
85
 
object they are destroyed).
86
 
</p>
87
 
 
88
 
<p>So, putting this all together, a simple plugin class may look something like the following:</p>
89
 
 
90
 
<pre class="code prettyprint">&#x2F;&#x2F; This AnchorPlugin is designed to be added to Node instances (the host will be a Node instance)
91
 
 
92
 
function AnchorPlugin(config) {
93
 
 
94
 
    &#x2F;&#x2F; Hold onto the host instance (a Node in this case), 
95
 
    &#x2F;&#x2F; for other plugin methods to use.
96
 
 
97
 
    this._node = config.host;
98
 
}
99
 
 
100
 
&#x2F;&#x2F; When plugged into a node instance, the plugin will be 
101
 
&#x2F;&#x2F; available on the &quot;anchors&quot; property.
102
 
AnchorPlugin.NS = &quot;anchors&quot;
103
 
 
104
 
AnchorPlugin.prototype = {
105
 
    disable: function() {
106
 
        var node = this._node;
107
 
        var anchors = node.queryAll(&quot;a&quot;);
108
 
        anchors.addClass(&quot;disabled&quot;);
109
 
        anchors.setAttribute(&quot;disabled&quot;, true);
110
 
    }
111
 
};</pre>
112
 
 
113
 
 
114
 
<p>To use the <code>AnchorPlugin</code>, the user would plug it into a Node reference they were holding on to:</p>
115
 
 
116
 
<pre class="code prettyprint">var container = Y.one(&quot;div.actions&quot;);
117
 
container.plug(AnchorPlugin);</pre>
118
 
 
119
 
 
120
 
<p>And invoke methods on the plugin, through the namespace it is bound to:</p>
121
 
 
122
 
<pre class="code prettyprint">container.anchors.disable();</pre>
123
 
 
124
 
 
125
 
<h3 id="advanced">Advanced Plugins</h3>
126
 
 
127
 
<p>For basic features, simple plugin classes as described above may suffice. However, when you have more complex features which you'd like to encapsulate, the ability to use 
128
 
attributes and events for your plugin implementation becomes useful. More importantly, for many plugins, you'll be looking to modify the default 
129
 
behavior of the host instance in some way (for example an Animation Plugin may want to change the default show/hide behavior of a Widget, to be animated).</p>
130
 
 
131
 
<p>For these richer plugins, you should extend the base plugin class <a href="http://yuilibrary.com/yui/docs/api/Plugin.Base.html"><code>Plugin.Base</code></a>. </p>
132
 
 
133
 
<p><code>Plugin</code> is a subclass of <code>Base</code>, thereby providing managed attributes, lifecycle methods, and custom event support. Additionally it allows the plugin code to 
134
 
either listen for and react to events fired by the host or inject custom logic before or after methods invoked on the host object (through the YUI 3 <a href="http://yuilibrary.com/yui/docs/api/Do.html">AOP</a> infrastructure).
135
 
<code>Plugin.Base</code> also sets up <code>host</code> as an attribute, so you can access it through <code>this.get(&quot;host&quot;)</code> in your plugin implementation code.
136
 
</p>
137
 
 
138
 
<h4 id="extendingplugin">Extending Plugin.Base</h4>
139
 
 
140
 
<p>You can extend the <code>Plugin.Base</code> class, just as you would extend the <a href="../base/index.html"><code>Base</code></a> class. One thing to note when comparing this to simple plugins 
141
 
is that the host reference is automatically set up as an attribute by the <code>Plugin.Base</code> class, so a reference to it does not need to be set up explicitly.</p>
142
 
 
143
 
<p>The class structure for an advanced plugin follows the pattern for all classes derived from Base, with the addition of the <code>NS</code> property to define
144
 
the namespace for the plugin (see the <a href="../base/index.html">Base</a> documentation for details about NAME and ATTRS).</p>
145
 
 
146
 
 
147
 
<pre class="code prettyprint">&#x2F;&#x2F; A plugin class designed to animate Widget&#x27;s show and hide methods.
148
 
function WidgetAnimPlugin(config) {
149
 
    WidgetAnimPlugin.superclass.constructor.apply(this, arguments);
150
 
}
151
 
 
152
 
&#x2F;&#x2F; Define Static properties NAME (to identify the class) and NS (to identify the namespace)
153
 
WidgetAnimPlugin.NAME = &#x27;widgetAnimPlugin&#x27;;
154
 
WidgetAnimPlugin.NS = &#x27;fx&#x27;;
155
 
 
156
 
&#x2F;&#x2F; Attribute definitions for the plugin
157
 
WidgetAnimPlugin.ATTRS = {
158
 
 
159
 
    animHidden : {
160
 
        ...
161
 
    },
162
 
 
163
 
    animVisible: {
164
 
        ...
165
 
    }
166
 
};
167
 
 
168
 
&#x2F;&#x2F; Extend Plugin.Base
169
 
Y.extend(WidgetAnimPlugin, Y.Plugin.Base, {
170
 
 
171
 
    &#x2F;&#x2F; Add any required prototype methods
172
 
 
173
 
});</pre>
174
 
 
175
 
 
176
 
<p>The plugin class structure described above is captured in this <a href="../assets/plugin/myplugin.js.txt">"MyPlugin" Template File</a>, which you can use as a starting point to create your own plugins derived from <code>Plugin.Base</code>.</p>
177
 
 
178
 
<h4 id="pluginlisteners">Plugin Listeners</h4>
179
 
 
180
 
<p>The main value obtained by extending <code>Plugin.Base</code> is the ability to react to events fired by the host  
181
 
using <code>Plugin.Base</code>'s <a href="http://yuilibrary.com/yui/docs/api/Plugin.Base.html#method_onHostEvent"><code>onHostEvent</code></a> and <a href="http://yuilibrary.com/yui/docs/api/Plugin.Base.html#method_afterHostEvent"><code>afterHostEvent</code></a> methods, or 
182
 
modify methods on the host, using <a href="http://yuilibrary.com/yui/docs/api/Plugin.Base.html#method_beforeHostMethod"><code>beforeHostMethod</code></a> and <a href="http://yuilibrary.com/yui/docs/api/Plugin.Base.html#method_afterHostMethod"><code>afterHostMethod</code></a>.</p>
183
 
 
184
 
<p>The value of doing this through the above <code>Plugin.Base</code> methods as opposed to working with the host directly, is that any listeners added by the plugin using the above methods are removed when the plugin is unplugged. 
185
 
This is important. Plugins should clean up after themselves when unplugged from the host.</p>
186
 
 
187
 
<h5 id="events">Events</h5>
188
 
 
189
 
<p>As mentioned, plugins which derive from <code>Plugin.Base</code> have the ability to listen for events on the host object and react to them.</p>
190
 
 
191
 
<p>For example, all widgets fire a <code>render</code> event when they are rendered. Your widget-specific plugin may need to know when this occurs, 
192
 
so that it can inject custom elements into the markup the host renders. It can do this through the <code>afterHostEvent</code> method:</p>
193
 
 
194
 
<pre class="code prettyprint">&#x2F;&#x2F; A plugin which introduces rounded corners to a widget.
195
 
function RoundedCornersPlugin(config) {
196
 
    &#x2F;&#x2F;...
197
 
}
198
 
 
199
 
RoundedCornersPlugin.NAME = &#x27;roundedCornersPlugin&#x27;;
200
 
RoundedCornersPlugin.NS = &#x27;corners&#x27;;
201
 
 
202
 
Y.extend(RoundedCornersPlugin, Y.Plugin.Base, {
203
 
 
204
 
    &#x2F;&#x2F; Automatically called by Base, during construction
205
 
    initializer: function(config) { 
206
 
         &#x2F;&#x2F; &quot;render&quot; is a widget event 
207
 
        this.afterHostEvent(&#x27;render&#x27;, this.insertCornerElements);
208
 
    },
209
 
 
210
 
    insertCornerElements: function() {
211
 
        var widget = this.get(&quot;host&quot;);
212
 
        var boundingBox = widget.get(&quot;boundingBox&quot;);
213
 
 
214
 
        var tl = Y.Node.create(TL_TEMPLATE);
215
 
        &#x2F;&#x2F;...
216
 
 
217
 
        boundingBox.appendChild(tlNode);
218
 
        boundingBox.appendChild(trNode);
219
 
        boundingBox.appendChild(blNode);
220
 
        boundingBox.appendChild(brNode);
221
 
    }
222
 
});</pre>
223
 
 
224
 
 
225
 
<h5 id="methods">Methods</h5>
226
 
 
227
 
<p>In some cases, your plugin may need to override the logic in the host class' methods. The <code>beforeHostMethod</code> and <code>afterHostMethod</code> methods provided by <code>Plugin.Base</code> 
228
 
allow you to insert custom plugin logic before or after a method is executed on the host object.</p>
229
 
 
230
 
<p>For example, to animate the way a widget is shown or hidden, we may need to override the method
231
 
which actually flips the visibility style attribute on the widget's bounding box and replace it with an animated opacity implementation, 
232
 
as shown below:</p>
233
 
    
234
 
<pre class="code prettyprint">&#x2F;&#x2F; A plugin class designed to animate Widget&#x27;s show and hide methods.
235
 
function WidgetAnimPlugin(config) {
236
 
    &#x2F;&#x2F;...
237
 
}
238
 
 
239
 
WidgetAnimPlugin.NAME = &#x27;widgetAnimPlugin&#x27;;
240
 
WidgetAnimPlugin.NS = &#x27;fx&#x27;;
241
 
 
242
 
WidgetAnimPlugin.ATTRS = {
243
 
 
244
 
    animHidden : {
245
 
        &#x2F;&#x2F;...
246
 
    },
247
 
 
248
 
    animVisible: {
249
 
        &#x2F;&#x2F;...
250
 
    }
251
 
};
252
 
 
253
 
&#x2F;&#x2F; Extend Plugin.Base, and override the default
254
 
&#x2F;&#x2F; method _uiSetVisible, used by Widget to flip the visibility
255
 
Y.extend(WidgetAnimPlugin, Y.Plugin.Base, {
256
 
 
257
 
    initializer : function(config) {
258
 
 
259
 
        &#x2F;&#x2F; Override Widget&#x27;s _uiSetVisible method, with the custom animated method
260
 
        this.beforeHostMethod(&quot;_uiSetVisible&quot;, this._uiAnimSetVisible);
261
 
    },
262
 
 
263
 
    _uiAnimSetVisible : function(show) {
264
 
        &#x2F;&#x2F; Instead of flipping visibility, use the animation
265
 
        &#x2F;&#x2F; instances configured for the plugin to animate
266
 
        &#x2F;&#x2F; hide&#x2F;show.
267
 
        if (this.get(&quot;host&quot;).get(&quot;rendered&quot;)) {
268
 
            if (show) {
269
 
                this.get(&quot;animHidden&quot;).stop();
270
 
                this.get(&quot;animVisible&quot;).run();
271
 
            } else {
272
 
                this.get(&quot;animVisible&quot;).stop();
273
 
                this.get(&quot;animHidden&quot;).run();
274
 
            }
275
 
 
276
 
            &#x2F;&#x2F; Prevent the default method from being invoked.
277
 
            return new Y.Do.Prevent();
278
 
        }
279
 
    }
280
 
});</pre>
281
 
 
282
 
</div>
283
 
        </div>
284
 
 
285
 
        <div id="sidebar" class="yui3-u">
286
 
            
287
 
                <div id="toc" class="sidebox">
288
 
                    <div class="hd">
289
 
                        <h2 class="no-toc">Table of Contents</h2>
290
 
                    </div>
291
 
 
292
 
                    <div class="bd">
293
 
                        <ul class="toc">
294
 
<li>
295
 
<a href="#getting-started">Getting Started</a>
296
 
</li>
297
 
<li>
298
 
<a href="#using">Creating Plugins</a>
299
 
<ul class="toc">
300
 
<li>
301
 
<a href="#simple">Simple Plugins</a>
302
 
</li>
303
 
<li>
304
 
<a href="#advanced">Advanced Plugins</a>
305
 
<ul class="toc">
306
 
<li>
307
 
<a href="#extendingplugin">Extending Plugin.Base</a>
308
 
</li>
309
 
<li>
310
 
<a href="#pluginlisteners">Plugin Listeners</a>
311
 
<ul class="toc">
312
 
<li>
313
 
<a href="#events">Events</a>
314
 
</li>
315
 
<li>
316
 
<a href="#methods">Methods</a>
317
 
</li>
318
 
</ul>
319
 
</li>
320
 
</ul>
321
 
</li>
322
 
</ul>
323
 
</li>
324
 
</ul>
325
 
                    </div>
326
 
                </div>
327
 
            
328
 
 
329
 
            
330
 
 
331
 
            
332
 
                <div class="sidebox">
333
 
                    <div class="hd">
334
 
                        <h2 class="no-toc">Examples That Use This Component</h2>
335
 
                    </div>
336
 
 
337
 
                    <div class="bd">
338
 
                        <ul class="examples">
339
 
                            
340
 
                                
341
 
                                    <li data-description="Shows how to create an IO plugin for Widget.">
342
 
                                        <a href="../widget/widget-plugin.html">Creating a Widget Plugin</a>
343
 
                                    </li>
344
 
                                
345
 
                            
346
 
                                
347
 
                                    <li data-description="Shows how to create a simple plugin to retrieve content for the Overlay using the io utility.">
348
 
                                        <a href="../overlay/overlay-io-plugin.html">IO Plugin</a>
349
 
                                    </li>
350
 
                                
351
 
                            
352
 
                                
353
 
                                    <li data-description="Shows how to create a simple plugin to animate the Overlay&#x27;s movement and visibility.">
354
 
                                        <a href="../overlay/overlay-anim-plugin.html">Animation Plugin</a>
355
 
                                    </li>
356
 
                                
357
 
                            
358
 
                        </ul>
359
 
                    </div>
360
 
                </div>
361
 
            
362
 
        </div>
363
 
    </div>
364
 
</div>
365
 
 
366
 
<script src="../assets/vendor/prettify/prettify-min.js"></script>
367
 
<script>prettyPrint();</script>
368
 
 
369
 
</body>
370
 
</html>