[Summary view] [Print] [Text view]

   1  YUI.add('gallery-bootstrap-engine', function(Y) {
   2  
   3  /**
   4   * Bootstrap Engine for Plug and Play widgets. This class is meant to be used in
   5   * conjuntion with the Injection Engine (gallery-bootstrap-engine). It facilitates the use of
   6   * an iframe as a sandbox to execute certain tasks and/or a presention element.
   7   *
   8   * @module gallery-bootstrap-engine
   9   * @requires node, base-base
  10   * @class Y.BootstrapEngine
  11   * @param config {Object} Configuration object
  12   * @extends Y.Base
  13   * @constructor
  14   */
  15  
  16  ///////////////////////////////////////////////////////////////////////////
  17  //
  18  // Private shorthands, constants and variables
  19  //
  20  ///////////////////////////////////////////////////////////////////////////
  21  
  22  var ATTR_HOST = 'host';
  23  
  24  ///////////////////////////////////////////////////////////////////////////
  25  //
  26  // Class definition
  27  //
  28  ///////////////////////////////////////////////////////////////////////////
  29  
  30  function BootstrapEngine () {
  31      BootstrapEngine.superclass.constructor.apply(this, arguments);
  32  }
  33  
  34  Y.mix(BootstrapEngine, {
  35  
  36      /**
  37       * The identity of the class.
  38       * @property BootstrapEngine.NAME
  39       * @type string
  40       * @static
  41       * @final
  42       * @readOnly
  43       * @default 'bootstrap'
  44       */
  45      NAME: 'bootstrap',
  46  
  47      /**
  48       * Static property used to define the default attribute configuration of
  49       * the class.
  50       * @property BootstrapEngine.ATTRS
  51       * @type Object
  52       * @protected
  53       * @static
  54       */
  55      ATTRS: {
  56          /**
  57           * @attribute container
  58           * @type {Selector|Node}
  59           * @writeOnce
  60           * @description selector or node for the iframe's container. This is relative to the parent document.
  61           */
  62          container: {
  63               getter: function (v) {
  64                   var host = this.get(ATTR_HOST);
  65                   return host && host.one( v );
  66               }
  67          },
  68          /**
  69           * @attribute iframe
  70           * @type {Node}
  71           * @readyOnly
  72           * @description Node reference to the iframe on the parent document.
  73           */
  74          iframe: {
  75              getter: function () {
  76                  var c = this.get('container');
  77                  return c && c.one('iframe' );
  78              }
  79          },
  80          /**
  81           * @attribute host
  82           * @type {Object}
  83           * @readyOnly
  84           * @description A "Y" reference bound to the parent document.
  85           */
  86          host: {
  87              readyOnly: true
  88          },
  89          /**
  90           * @attribute ready
  91           * @type {Boolean}
  92           * @readyOnly
  93           * @description A "Y" reference bound to the parent document.
  94           */
  95          ready: {
  96              value: false,
  97              readyOnly: true
  98          }
  99      }
 100  
 101  });
 102  
 103  Y.extend(BootstrapEngine, Y.Base, {
 104      /**
 105       * Any extra YUI module that you want to use by default in HOST YUI instance.
 106       * "node" module will be added automatically since it's required by bootstrap.
 107       * @property EXTRAS
 108       * @type Array
 109       * @default []
 110       */
 111      EXTRAS: [],
 112  
 113      /**
 114       * Construction logic executed during Bootstrap Engine instantiation.
 115       *
 116       * @method initializer
 117       * @param cfg {Object} Initial configuration
 118       * @protected
 119       */
 120      initializer: function () {
 121          var instance = this,
 122              parent, win, doc,
 123              use = Y.Array(instance.EXTRAS),
 124              host,
 125              callBootFn = function () {
 126                  // finishing the initialization process async to facilitate
 127                  // addons to hook into _boot/_init/_bind/_ready if needed.
 128                  // todo: after migrating to 3.4 this is not longer needed, and we can use initializer and destroyer
 129                  // in each extension
 130                  Y.later(0, instance, function() {
 131                      instance._boot();
 132                  });
 133              };
 134  
 135          try {
 136              parent = Y.config.win.parent;
 137              win = parent && parent.window;
 138              doc = win && win.document;
 139          } catch(e) {
 140              Y.log ('Parent window is not available or is a different domain', 'warn', 'bootstrap');
 141          }
 142  
 143          Y.log ('Initialization', 'info', 'bootstrap');
 144          // parent is optional to facilitate testing and headless execution
 145          if (parent && win && doc) {
 146              host = YUI({
 147                  bootstrap: false,
 148                  win: win,
 149                  doc: doc
 150              });
 151              use.push('node', function() {
 152                  callBootFn();
 153              });
 154  
 155              // Creating a new YUI instance bound to the parent window
 156              instance._set(ATTR_HOST, host.use.apply(host, use));
 157          } else {
 158              callBootFn();
 159          }
 160      },
 161  
 162      /**
 163       * Basic initialization routine, styling the iframe, binding events and
 164       * connecting the bootstrap engine with the injection engine.
 165       *
 166       * @method _boot
 167       * @protected
 168       */
 169      _boot: function () {
 170          var instance = this,
 171              auto;
 172          Y.log ('Boot', 'info', 'bootstrap');
 173          // connecting with the injection engine before doing anything else
 174          auto = instance._connect();
 175          // adjust the iframe container in preparation for the first display action
 176          instance._styleIframe();
 177          // create some objects and markup
 178          instance._init();
 179          // binding some extra events
 180          instance._bind();
 181          // if the connect process wants to automatically execute the _ready, it should returns true.
 182          if (auto) {
 183              // connecting the bootstrap with the injection engine
 184              instance._ready();
 185          }
 186          // marking the system as ready
 187          instance._set('ready', true);
 188      },
 189  
 190      /**
 191       * Connects the bootstrap with the injection engine running in the parent window. This method
 192       * defines the hand-shake process between them. This method is meant to be called by
 193       * the bootstrap engine _init method to start the connection.
 194       *
 195       * @method _connect
 196       * @protected
 197       */
 198      _connect: function () {
 199          var guid = Y.config.guid, // injection engine guid value
 200              host = this.get(ATTR_HOST),
 201              pwin = host && host.config.win,
 202              // getting a reference to the parent window callback function to notify
 203              // to the injection engine that the bootstrap is ready
 204              callback = guid && pwin && pwin.YUI && pwin.YUI.Env[guid];
 205  
 206          Y.log ('Bootstrap connect', 'info', 'bootstrap');
 207          // connecting bootstrap with the injection engines
 208          return ( callback ? callback ( this ) : false );
 209      },
 210  
 211      /**
 212       * Basic initialization routine, usually to create markup, new objects and attributes, etc.
 213       * Overrides/Extends this prototype method to do your mojo.
 214       *
 215       * @method _init
 216       * @protected
 217       */
 218      _init: function () {
 219          Y.log ('Init bootstrap', 'info', 'bootstrap');
 220      },
 221  
 222      /**
 223       * Defines the binding logic for the bootstrap engine, listening for some attributes
 224       * that might change, and defining the set of events that can be exposed to the injection engine.
 225       * Overrides/Extends this prototype method to do your mojo.
 226       *
 227       * @method _bind
 228       * @protected
 229       */
 230      _bind: function () {
 231          Y.log ('Binding bootstrap', 'info', 'bootstrap');
 232      },
 233  
 234      /**
 235       * This method will be called only if the connect response with "true", you can use this
 236       * to control the state of the initialization from the injection engine since it might
 237       * take some time to load the stuff in the iframe, and the user might interact with the page
 238       * invalidating the initialization routine.
 239       * Overrides/Extends this prototype method to do your mojo.
 240       *
 241       * @method _ready
 242       * @protected
 243       */
 244      _ready : function () {
 245           Y.log ('Bootstrap is ready', 'info', 'bootstrap');
 246       },
 247  
 248       /**
 249        * The iframe that holds the bootstrap engine sometimes is used as a UI overlay.
 250        * In this case, you can style it through this method. By default, it will set
 251        * border, frameBorder, marginWidth, marginHeight, leftMargin and topMargin to
 252        * cero, and allowTransparency to true.
 253        *
 254        * @method _styleIframe
 255        * @protected
 256        */
 257       _styleIframe: function () {
 258           var iframe = this.get('iframe');
 259           // making the iframe optional to facilitate tests
 260           if (iframe) {
 261               Y.log ('Styling the iframe', 'info', 'bootstrap');
 262               Y.each (['border', 'marginWidth', 'marginHeight', 'leftMargin', 'topMargin'], function (name) {
 263                   iframe.setAttribute(name, 0);
 264               });
 265           }
 266       }
 267  
 268  });
 269  
 270  Y.BootstrapEngine = BootstrapEngine;
 271  
 272  
 273  }, '@VERSION@' ,{requires:['node','base-base']});