<style>
#demo {
    width: 50em;
}
.yui3-widget-content {
    border:1px solid #000;
    padding:1em;
}
.yui3-tab-loading {
    background: #fff url({{componentAssets}}/img/ajax-loader.gif) no-repeat center center;
    height:40px;
}
</style>

<div class="intro">
    <p>This example shows how you can use Widget's plugin infrastructure to add additional features to an existing widget.</p>
    <p>
        We use the `"gallery-widget-io"` plugin to add io capabilities bound to a widget instance. The plugin provides an `io` interface on Widget, which can be used to update
        the widget's contentBox contents.
    </p>
    <p><strong>NOTES:</strong> 
        <ul>
            <li>For <a href="http://yuilibrary.com/yui/docs/io/index.html#security-bulletin">Security reasons</a>, YUI has made the decision to <a href="https://github.com/yui/yui3/issues/845">remove all Flash files from the repository</a>. As a result, this example will not function as it relies on Flash for the cross-domain transport. The code for this example will work if you compile and host the <code>io.swf</code> file. Necessary source files for compilation are available in the <a href="https://github.com/yui/yui3-swfs">yui3-swfs</a> repository.</li>
            <li> This example will not function on iOS devices due to the usage of Flash as the cross-domain transport.  This example may not work on older Android devices, as well.</li>
        </ul>
    </p>
</div>

<div class="example">
    {{>widget-plugin-source}}
</div>

<h2>Using The Gallery IO Plugin For Widget</h2>

<h3>Setting Up The YUI Instance</h3>

<p>For this example, we'll pull in `widget`; the `gallery-widget-io` plugin, and the `json-parse` modules to help us work with the JSON RSS data returned.
 The code to set up our sandbox instance is shown below:</p>

```
YUI().use("widget", "gallery-widget-io", "json-parse", function(Y) {
    // We'll write our code here, after pulling in the default Widget module,
    // the IO plugin.
});
```

<h3>The Widget IO Plugin</h3>

<p>The Widget IO plugin is a fairly simple plugin. 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/overlay-anim-plugin.html">AnimPlugin</a> example).</p>

<p>It sets up the following attributes, which are used to control how the IO plugin's `refresh` method behaves:</p>

<dl>
    <dt>uri</dt>
    <dd>The uri to use for the io request</dd>
    <dt>cfg</dt>
    <dd>The io configuration object, to pass to io when initiating a transaction</dd>
    <dt>formatter</dt>
    <dd>The formatter to use to formatting response data. The default implementation simply passes back the response data passed in, unchanged.</dd>
    <dt>loading</dt>
    <dd>The default content to display while an io transaction is in progress</dd>
</dl>

<h3>Using the Plugin</h3>

<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.
They 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>

<p>In this example, we'll create a new instance of a Widget:</p>

```
/* Create a new Widget instance, with content generated from script */
var widget = new Y.Widget();
```

<p>And then use the `plug` method to add the `WidgetIO` plugin,
providing it with a configuration to use when sending out io transactions
(The <a href="../overlay/overlay-anim-plugin.html">Animation Plugin</a> example shows how
you could do the same thing during construction), render the widget, and refresh
the plugin to fetch the content.</p>

```
/*
 * Add the Plugin, and configure it to use a news feed uri, and work cross-domain, using xdr
 */
widget.plug(Y.Plugin.WidgetIO, {
    uri : 'http:/' + '/pipes.yahooapis.com/pipes/pipe.run?_id=6b7b2c6a32f5a12e7259c36967052387&_render=json&url=http:/' + '/rss.news.yahoo.com/rss/us',
    cfg:{
        xdr: {
            use:'flash'
        }
    },
    formatter: formatRSS,
    loading: '<img class="yui3-loading" width="32px" height="32px" src="{{componentAssets}}/img/ajax-loader.gif">'
});

widget.render('#demo');

/* fetch the content */
widget.io.refresh();
```

<p>We pass in a formatter to the io plugin, which is responsible for translating the JSON RSS from the uri to HTML:</p>

```
var formatRSS = function (val) {
    var formatted = "Error parsing feed data";
    try {
        var json = Y.JSON.parse(val);

        if (json && json.count) {
            var html = ['<ul class="yui3-feed-data">'];
            var linkTemplate = '<li><a href="{link}" target="_blank">{title}</a></li>';

            Y.each(json.value.items, function(v, i) {
                if (i < 10) {
                    v.title = Y.Escape.html(v.title);
                    v.link = Y.Escape.html(v.link);
                    html.push(Y.Lang.sub(linkTemplate, v));
                }
            });
            html.push("</ul>");
            formatted = html.join("");
        } else {
            formatted = "No Data Available";
        }
    } catch(e) {
        formatted = "Error parsing feed data";
    }
    return formatted;
};
```

<p>NOTE: Since we're using `IO`'s XDR functionality for this example, we wrap the widget construction in a callback which notifies us when the flash XDR module is ready to service requests. In your local implementations,
if you're not sending cross-domain requests, you don't need to use the XDR functionality and leave out the code below:</p>

```
Y.on('io:xdrReady', function() {
    // Setup Widget when io xdr is available
});

// Set up io to use the flash XDR transport
Y.io.transport({
    id:'flash',
    yid: Y.id,
    src:'io.swf?stamp=' + (new Date()).getTime() //Relative path to the .swf file from the current page.
});
```

<h2>Complete Example Source</h2>
```
{{>widget-plugin-source}}
```
