widget-plugin.mustache revision e808b8824ca1091c8efb5669db9129e68e5e1c14
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<style scoped>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai width: 50em;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai.yui3-widget-content {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai border:1px solid #000;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai padding:1em;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai.yui3-tab-loading {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai background: #fff url({{componentAssets}}/img/ajax-loader.gif) no-repeat center center;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai height:40px;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<div class="intro">
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai <p>This example shows how you can use Widget's plugin infrastructure to add additional features to an existing widget.</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai <p>We create an IO plugin class for `Widget` called `WidgetIO`. The plugin adds IO capabilities to the Widget, which, by default, outputs to the `Widget`'s `contentBox`.</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<div class="example">
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai {{>widget-plugin-source}}
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<h2>Creating an IO Plugin For Widget</h2>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<h3>Setting Up The YUI Instance</h3>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>For this example, we'll pull in `widget`; the `io`, and
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaithe `plugin` module. The `io` module provides the XHR
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaisupport we need for the IO plugin. The `Plugin` base class is the class we'll
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaiextend to create our io plugin class for `Widget`.
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen DesaiThe code to set up our sandbox instance is shown below:</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen DesaiYUI({...}).use("widget", "io", "plugin", function(Y) {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai // We'll write our code here, after pulling in the default Widget module,
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai // the IO utility, and the Plugin base class.
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>Using the `widget` module will also pull down the default CSS required for widget, on top of which we only need to add our required look/feel CSS for the example.</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<h3>WidgetIO Class Structure</h3>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>The `WidgetIO` class will extend the `Plugin` base class. Since `Plugin` derives from `Base`, we follow the same pattern we use for widgets and other utilities which extend Base to setup our new class.</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>Namely:</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai <li>Setting up the constructor to invoke the superclass constructor</li>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai <li>Setting up a `NAME` property, to identify the class</li>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai <li>Setting up the default attributes, using the `ATTRS` property</li>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai <li>Providing prototype implementations for anything we want executed during initialization and destruction using the `initializer` and `destructor` lifecycle methods</li>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>Additionally, since this is a plugin, we provide a `NS` property for the class, which defines the property which will refer to the `WidgetIO` instance on the host class (e.g. `widget.io` will be an instance of `WidgetIO`)</p>.
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai/* Widget IO Plugin Constructor */
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaifunction WidgetIO(config) {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai WidgetIO.superclass.constructor.apply(this, arguments);
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai * The namespace for the plugin. This will be the property on the widget,
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai * which will reference the plugin instance, when it's plugged in
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai * The NAME of the WidgetIO class. Used to prefix events generated
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai * by the plugin class.
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai * The default set of attributes for the WidgetIO class.
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai uri : {...},
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai cfg : {...},
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai formatter : {...},
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai loading: {...}
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai/* Extend the base plugin class */
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai // Lifecycle methods.
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai initializer: function() {...},
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai // IO Plugin specific methods
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai refresh : function() {...},
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai // Default IO transaction handlers
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai _defSuccessHandler : function(id, o) {...},
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai _defFailureHandler : function(id, o) {...},
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai _defStartHandler : function(id, o) {...},
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai _defCompleteHandler : function(id, o) {...},
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai _defFormatter : function(val) {...}
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<h3>Plugin Attributes</h3>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>The `WidgetIO` is a fairly simple plugin class. It provides incremental functionality. It does not need to modify the behavior of any methods on the host Widget instance, or monitor any Widget events (unlike the <a href="overlay-anim-plugin.html">AnimPlugin</a> example).</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>It sets up the following attributes, which are used to control how the IO plugin's `refresh` method behaves:</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai <dt>uri</dt>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai <dd>The uri to use for the io request</dd>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai <dt>cfg</dt>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai <dd>The io configuration object, to pass to io when initiating a transaction</dd>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai <dt>formatter</dt>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai <dd>The formatter to use to formatting response data. The default implementation simply passes back the response data passed in, unchanged.</dd>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai <dt>loading</dt>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai <dd>The default content to display while an io transaction is in progress</dd>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>In terms of code, the attributes for the plugin are set up using the standard `ATTRS` property:</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai/* Setup local variable for Y.WidgetStdMod, since we use it
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai multiple times to reference static properties */
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaivar WidgetIO = Y.WidgetIO;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai/* Attribute definition */
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai * The node that will contain the IO content
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai contentNode: {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai value: '.yui3-widget-content',
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai setter: '_defContentNodeSetter'
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai * The uri to use for the io request
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai * The io configuration object, to pass to io when initiating
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai * a transaction
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai * The default formatter to use when formatting response data. The default
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai * implementation simply passes back the response data passed in.
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai formatter : {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai valueFn: function() {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai return this._defFormatter;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai * The default loading indicator to use, when an io transaction is in progress.
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai value: '<img class="yui3-loading" width="32px" \
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai height="32px" src="{{componentAssets}}/img/ajax-loader.gif">'
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>The `formatter` attribute uses `valueFn` to define an instance based default value; pointing to the `_defFormatter` method on the `WidgetIO` instance.</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<h3>Lifecycle Methods: initializer, destructor</h3>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>Since no special initialization is required, there is no need to implement an `initializer` method.</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>The `destructor` terminates any existing transaction, if active when the plugin is destroyed (unplugged).</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaiinitializer: function() {}
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai * Destruction code. Terminates the activeIO transaction if it exists
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaidestructor : function() {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai if (this._activeIO) {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai Y.io.abort(this._activeIO);
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai this._activeIO = null;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<h3>The refresh Method</h3>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>The `refresh` method is the main public method which the plugin provides. It's responsible for dispatching the IO request, using the current state of the attributes defined of the plugin. Users will end up invoking the method from the plugin instance attached to the Widget (`widget.io.refresh()`).</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desairefresh : function() {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai if (!this._activeIO) {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai var uri = this.get("uri");
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai cfg = this.get("cfg") || {};
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai cfg.on.start = cfg.on.start || Y.bind(this._defStartHandler, this);
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai cfg.on.complete = cfg.on.complete || Y.bind(this._defCompleteHandler, this);
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai cfg.on.success = cfg.on.success || Y.bind(this._defSuccessHandler, this);
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai cfg.on.failure = cfg.on.failure || Y.bind(this._defFailureHandler, this);
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai cfg.method = cfg.method; // io defaults to "GET" if not defined
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>The `refresh` method, as implemented for the scope of this example, sets up the io configuration object for the transaction it is about to dispatch, filling in the default handlers for io's `start`, `complete`, `success` and `failure` events, if the user does not provide custom implementations.</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<h3>Node Content Helper Method</h3>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>To simplify implementation and extension, a `setContent` method is used to
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaiwrap the content setter, which by default updates the `contentBox` of the widget.</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai * Helper method for setting host content
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen DesaisetContent: function(content) {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai this.get('contentNode').setContent(content);
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<h3>The Default IO Event Handlers</h3>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>The default success listener, pulls the response data from the response object, and uses it to update the content
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaidefined by the `contentNode` attribute, which, by default, is the `contentBox`. The response data is passed through the `formatter` configured for the plugin, converting it to the desired output format:</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai_defSuccessHandler : function(id, o) {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai var response = o.responseXML || o.responseText;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai var formatter = this.get('formatter');
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai this.setContent(formatter(response));
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>The default failure listener, displays an error message in the currently configured `section`, when io communication fails:</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai_defFailureHandler : function(id, o) {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai this.setContent('Failed to retrieve content');
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>The default start event listener renders the `loading` content, which remains in place while the transaction is in process, and also stores a reference to the "inprogress" io transaction:</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai_defStartHandler : function(id, o) {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai this._activeIO = o;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>The default complete event listener clears out the "inprogress" io transaction object:</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai_defCompleteHandler : function(id, o) {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai this._activeIO = null;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<h3>Using the Plugin</h3>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>All objects derived from <a href="{{apiDocs}}/Base.html">Base</a> are <a href="{{apiDocs}}/Plugin.Host.html">Plugin Hosts</a>. They provide <a href="{{apiDocs}}/Plugin.Host.html#method_plug">`plug`</a> and <a href="{{apiDocs}}/Plugin.Host.html#method_unplug">`unplug`</a> methods to allow users to add/remove plugins to/from existing instances.
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen DesaiThey also allow the user to specify the set of plugins to be applied to a new instance, along with their configurations, as part of the constructor arguments.</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>In this example, we'll create a new instance of a Widget:</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai/* Create a new Widget instance, with content generated from script */
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaivar widget = new Y.Widget();
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>And then use the `plug` method to add the `WidgetIO`,
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaiproviding it with a configuration to use when sending out io transactions
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai(The <a href="overlay-anim-plugin.html">Animation Plugin</a> example shows how
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaiyou could do the same thing during construction), render the widget, and refresh
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaithe plugin to fetch the content.</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai * Add the Plugin, and configure it to use a news feed uri
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai uri : '{{componentAssets}}/news.php?query=web+browser',
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai loading: '<img class="yui3-loading" width="32px" height="32px" src="{{componentAssets}}/img/ajax-loader.gif">'
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai/* fetch the content */
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>The plugin class structure described above is captured in this <a href="{{componentAssets}}/../plugin/myplugin.js.txt">"MyPlugin" Template File</a>, which you can use as a starting point to create your own plugins derived from `Plugin.Base`.</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<h2>Complete Example Source</h2>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai{{>widget-plugin-source}}