overlay-io-plugin.mustache revision e808b8824ca1091c8efb5669db9129e68e5e1c14
36983956d7c3d9e294903eeda29548f67ac17daeBob Halley<style type="text/css" scoped>
40d01ce8f3a1889f5799d9b22b26d5398fa75a1bBob Halley .yui3-overlay-content {
b90dd6c0a9df584619d3c47be7c9417f55d5ccf6Bob Halley padding:5px;
16803617e47c83272013e45ba8eb83a3b11983edAndreas Gustafsson background-color:#ccc;
16803617e47c83272013e45ba8eb83a3b11983edAndreas Gustafsson border:1px solid #000;
16803617e47c83272013e45ba8eb83a3b11983edAndreas Gustafsson .yui3-overlay .yui3-widget-hd,
16803617e47c83272013e45ba8eb83a3b11983edAndreas Gustafsson .yui3-overlay .yui3-widget-bd,
16803617e47c83272013e45ba8eb83a3b11983edAndreas Gustafsson .yui3-overlay .yui3-widget-ft {
16803617e47c83272013e45ba8eb83a3b11983edAndreas Gustafsson background-color:#eee;
fd9b6f253eac9dae2e1ad19d49aaa922d5d4f274Mark Andrews border:1px solid #999;
16803617e47c83272013e45ba8eb83a3b11983edAndreas Gustafsson text-align:left;
16803617e47c83272013e45ba8eb83a3b11983edAndreas Gustafsson .yui3-overlay .yui3-widget-bd {
16803617e47c83272013e45ba8eb83a3b11983edAndreas Gustafsson background-color:#fff;
16803617e47c83272013e45ba8eb83a3b11983edAndreas Gustafsson text-align:center;
16803617e47c83272013e45ba8eb83a3b11983edAndreas Gustafsson vertical-align:middle;
16803617e47c83272013e45ba8eb83a3b11983edAndreas Gustafsson .yui3-overlay .yui3-widget-bd .yui3-feed-data {
16803617e47c83272013e45ba8eb83a3b11983edAndreas Gustafsson text-align:left;
16803617e47c83272013e45ba8eb83a3b11983edAndreas Gustafsson .yui3-overlay .yui3-feed-selector .yui3-prompt {
16803617e47c83272013e45ba8eb83a3b11983edAndreas Gustafsson font-weight:bold;
b90dd6c0a9df584619d3c47be7c9417f55d5ccf6Bob Halley .yui3-widget-loading .yui3-widget-bd {
b90dd6c0a9df584619d3c47be7c9417f55d5ccf6Bob Halley background: #fff url({{componentAssets}}/img/ajax-loader.gif) no-repeat center center;
16803617e47c83272013e45ba8eb83a3b11983edAndreas Gustafsson<div class="intro">
16803617e47c83272013e45ba8eb83a3b11983edAndreas Gustafsson <p>This example shows how you can use Widget's plugin infrastructure to add additional features to an existing widget.</p>
16803617e47c83272013e45ba8eb83a3b11983edAndreas Gustafsson <p>We create an IO plugin class for `Overlay` called `StdModIOPlugin`. The plugin adds IO capabilities to the Overlay, bound to one of its standard module sections <em>(header, body or footer)</em>.</p>
276a77c22af98c78403883b16a82646a0d5b29abPaul Vixie<div class="example>
40d01ce8f3a1889f5799d9b22b26d5398fa75a1bBob Halley {{>overlay-io-plugin-source}}
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt<h2>Creating an IO Plugin For Overlay</h2>
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt<h3>Setting Up The YUI Instance</h3>
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt<p>For this example, we'll start from the Widget IO plugin (gallery-io-plugin) created in the <a href="widget-plugin.html">widget plugin example</a>, pull in `overlay`; `json` and `substitute` utility modules
af104911b781444e0b2d3da9df553897e511303aEvan Huntand the `plugin` module. The Widget IO plugin will pull in the dependencies it needs, the main one being `io` to provide the XHR support.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan HuntThe `json` and `substitute` modules provide the support we need to parse/transform JSON responses into HTML.The code to set up our sandbox instance is shown below:</p>
553ead32ff5b00284e574dcabc39115d4d74ec66Evan HuntYUI({...}).use("overlay", "substitute", "json", "gallery-io-plugin", function(Y) {
b272d38cc5d24f64c0647a9afb340c21c4b9aaf7Evan Hunt // We'll write our code here, after pulling in the default Overlay widget,
b272d38cc5d24f64c0647a9afb340c21c4b9aaf7Evan Hunt // the IO utility, the Plugin.WidgetIO base class along with the
b272d38cc5d24f64c0647a9afb340c21c4b9aaf7Evan Hunt // Substitute and JSON utilities
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt<p>Using the `overlay` module will also pull down the default CSS required for overlay, on top of which we only need to add our required look/feel CSS for the example.</p>
d699672160ba01589227ac046a28e20d55336facEvan Hunt<h3>StdModIO Class Structure</h3>
d699672160ba01589227ac046a28e20d55336facEvan Hunt<p>The `StdModIO` class will extend the `Plugin.WidgetIO` base class.
d699672160ba01589227ac046a28e20d55336facEvan HuntSince `WidgetIO` derives from `Pluing.Base` and hence `Base`, we follow the same
0e4fda8862cc0d04a54faba5c54eab5e7517ec58Evan Huntpattern we use for widgets and other utilities which extend Base to setup our new class.</p>
d699672160ba01589227ac046a28e20d55336facEvan Hunt<p>Namely:</p>
40d0f115a64595aa83cfe0b760587d3d1efa0385Tatuya JINMEI 神明達哉 <li>Setting up the default attributes, using the `ATTRS` property</li>
28479307225582ad0b2e11441d85fcf5169551d0Mark Andrews <li>Calling the superclass constructor</li>
28479307225582ad0b2e11441d85fcf5169551d0Mark Andrews <li>Setting up the the `NAME` property</li>
28479307225582ad0b2e11441d85fcf5169551d0Mark Andrews <li>Providing prototype implementations for anything we want executed during initialization and destruction using the `initializer` and `destructor` lifecycle methods</li>
6cdaeb94d4d12b72b919f3c7099f7c47c172b59bEvan Hunt<p>Additionally, since this is a plugin, we provide a `NS` property for the class, which defines the property which will refer to the `StdModIO` instance on the host class (e.g. `overlay.io` will be an instance of `StdModIO`)</p>.
6cdaeb94d4d12b72b919f3c7099f7c47c172b59bEvan HuntStdModIO = function(config) {
6cdaeb94d4d12b72b919f3c7099f7c47c172b59bEvan Hunt StdModIO.superclass.constructor.apply(this, arguments);
6cdaeb94d4d12b72b919f3c7099f7c47c172b59bEvan Hunt initializer: function() {...}
6cdaeb94d4d12b72b919f3c7099f7c47c172b59bEvan Hunt section: {...}
f6f1672b4e460571c418e43ae3bd0fae97e4c149Mark Andrews NAME: 'StdModIO',
5a8bebe00df211d4fdac3edc36cf35e1d5af42e0Mark Andrews<h3>Plugin Attributes</h3>
5a8bebe00df211d4fdac3edc36cf35e1d5af42e0Mark Andrews<p>The `StdModIO` is a fairly simple plugin class. It provides
5a8bebe00df211d4fdac3edc36cf35e1d5af42e0Mark Andrewsincremental functionality. It does not need to modify the behavior of any
5a8bebe00df211d4fdac3edc36cf35e1d5af42e0Mark Andrewsmethods on the host Overlay instance, or monitor any Overlay events
5a8bebe00df211d4fdac3edc36cf35e1d5af42e0Mark Andrews(unlike the <a href="overlay-anim-plugin.html">AnimPlugin</a> example).</p>
5a8bebe00df211d4fdac3edc36cf35e1d5af42e0Mark Andrews<p>In terms of code, the attributes for the plugin are set up using the standard
2fff8b8280779a25fbdb891b2d3d9b435d2084f0Tatuya JINMEI 神明達哉`ATTRS` property. For this example, we will add an attribute called
2fff8b8280779a25fbdb891b2d3d9b435d2084f0Tatuya JINMEI 神明達哉`section` that represents which part of the module (e.g. "header",
19bcb91965916ed8f0a47da2284ddaecce70bc69Evan Hunt"body", or "footer") will be updated with the returned content.</p>
ffc65cc90db78a67171e3d91f63f2e92d09d2d38Evan Hunt * The Standard Module section to which the io plugin instance is bound.
ffc65cc90db78a67171e3d91f63f2e92d09d2d38Evan Hunt * Response data will be used to populate this section, after passing through
767c53c304b86460d72eeec7d3304172cdd904bdEvan Hunt * the configured formatter.
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews validator: function(val) {
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews return (!val || val == StdMod.BODY
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews<h3>Lifecycle Methods: initializer, destructor</h3>
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews<p>The base `WidgetIO` plugin implements the `initializer`
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrewsand `destructor` lifecycle methods. For the purposes of this example,
e80b69327290953b825c7778d8de9d314bed6198Mark Andrewswe will extend the `StdModIO` plugin's `initializer` so that it
e80b69327290953b825c7778d8de9d314bed6198Mark Andrewsactivates the Flash based <a href="../../io/#xdr">XDR</a> transport so that the
e80b69327290953b825c7778d8de9d314bed6198Mark Andrewsplugin is able to dispatch both in-domain and cross-domain requests
e80b69327290953b825c7778d8de9d314bed6198Mark Andrews(the transport used for any particular uri is controlled through the plugin's
e80b69327290953b825c7778d8de9d314bed6198Mark Andrews`cfg` attribute).</p>
e80b69327290953b825c7778d8de9d314bed6198Mark Andrewsinitializer: function() {
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews // We setup a flag, so that we know if
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews // flash is available to make the
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews // XDR request.
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews Y.on('io:xdrReady', function() {
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews transportAvailable = true;
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews src:'../../build/io/io.swf?stamp=' + (new Date()).getTime()
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews<h3>Using the Plugin</h3>
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews<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.
309a3b5808b3e7666d219665c28768e5c0997f14Mark AndrewsThey 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>
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews<p>In this example, we'll create a new instance of an Overlay:</p>
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews/* Create a new Overlay instance, with content generated from script */
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrewsvar overlay = new Y.Overlay({
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews width:"40em",
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews visible:false,
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews node:"#show",
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews points: [Y.WidgetPositionAlign.TL, Y.WidgetPositionAlign.BL]
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews headerContent: generateHeaderMarkup(),
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews bodyContent: "Feed data will be displayed here"
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews<p>And then use the `plug` method to add the `StdModIO`, providing it with a configuration to use when sending out io transactions (The <a href="overlay-anim-plugin.html">Animation Plugin</a> example shows how you could do the same thing during construction):</p>
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews * Add the Standard Module IO Plugin, and configure it to use flash,
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews * and a formatter specific to the pipes response we're expecting
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews * from the uri request we'll send out.
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews uri : pipes.baseUri + pipes.feeds["ynews"].uri,
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews loading: '<img class="yui3-loading" width="32px" height="32px" src="{{componentAssets}}/img/ajax-loader.gif">'
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews<p>For this example, the io plugin is configured to use the `flash` cross-domain transport, to send out requests to the pipes API for the feed the user selects from the dropdown.</p>
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews<h3>Getting Feed Data Through Pipes</h3>
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews<p>We setup an object (`pipes`) to hold the feed URIs, which can be looked up and passed to the plugin to dispatch requests for new data:</p>
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews/* The Pipes feed URIs to be used to dispatch io transactions */
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrewsvar pipes = {
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews baseUri : 'http:/'+'/pipes.yahooapis.com/pipes/pipe.run? \
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews _id=6b7b2c6a32f5a12e7259c36967052387& \
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews _render=json&url=http:/'+'/',
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews title: 'Yahoo! US News',
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews title: 'YUI Blog',
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews uri: 'feeds.yuiblog.com/YahooUserInterfaceBlog'
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews slashdot : {
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews title: 'Slashdot',
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews<p>The data structure also holds the default formatter (`pipes.formatter`) required to convert the JSON responses from the above URIs to HTML. The JSON utility is first used to parse the json response string. The resulting object is iterated around, using Y.each, and substitute is used to generate the list markup:</p>
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews// The default formatter, responsible for converting the JSON responses received,
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews// into HTML. JSON is used for the parsing step, and substitute for some basic
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews// templating functionality
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrewsformatter : function (val) {
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews var formatted = "Error parsing feed data";
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews var json = Y.JSON.parse(val);
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews if (json && json.count) {
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews var html = ['<ul class="yui3-feed-data">'];
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews var linkTemplate =
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews '<li><a href="{link}" target="_blank">{title}</a></li>';
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews // Loop around all the items returned, and feed
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews // them into the template above, using substitute.
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews if (i < 10) {
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews formatted = html.join("");
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews formatted = "No Data Available";
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews } catch(e) {
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews formatted = "Error parsing feed data";
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews return formatted;
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews<p>The `change` handler for the select dropdown binds everything together, taking the currently selected feed, constructing the URI for the feed, setting it on the plugin, and sending out the request:</p>
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews/* Handle select change */
309a3b5808b3e7666d219665c28768e5c0997f14Mark AndrewsY.on("change", function(e) {
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews var val = this.get("value");
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews if (transportAvailable) {
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews if (val != -1) {
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews overlay.io.set("uri", pipes.baseUri + pipes.feeds[val].uri);
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews overlay.io.setContent("Flash doesn't appear to be available. Cross-domain requests to pipes cannot be made without it.");
309a3b5808b3e7666d219665c28768e5c0997f14Mark Andrews}, "#feedSelector");
c45ca0b839adc61c7902aad0969de36921b292b0Mark Andrews<h2>Complete Example Source</h2>
c45ca0b839adc61c7902aad0969de36921b292b0Mark Andrews{{>overlay-io-plugin-source}}