[Summary view] [Print] [Text view]

   1  YUI.add('yui2-imageloader', function(Y) {
   2      var YAHOO    = Y.YUI2;
   3      /*
   4  Copyright (c) 2011, Yahoo! Inc. All rights reserved.
   5  Code licensed under the BSD License:
   6  http://developer.yahoo.com/yui/license.html
   7  version: 2.9.0
   8  */
   9  /**
  10   * The ImageLoader Utility is a framework to dynamically load images according to certain triggers,
  11   * enabling faster load times and a more responsive UI.
  12   *
  13   * @module imageloader
  14   * @namespace YAHOO.util.ImageLoader
  15   * @requires yahoo, dom, event
  16   */
  17  
  18  if (typeof(YAHOO.util.ImageLoader) == 'undefined') {
  19      YAHOO.util.ImageLoader = {};
  20  }
  21  
  22  /**
  23   * A group for images. A group can have one time limit and a series of triggers. Thus the images belonging to this group must share these constraints.
  24   * @class YAHOO.util.ImageLoader.group
  25   * @requires YAHOO.util.Dom
  26   * @requires YAHOO.util.Event
  27   * @constructor
  28   * @param {String|HTMLElement}    trigEl    The HTML element id or reference to assign the trigger event to. Can be null for no trigger
  29   * @param {String}    trigAct The type of event to assign to trigEl. Can be null for no trigger
  30   * @param {Number}    timeout    Timeout (time limit) length, in seconds. Can be undefined, or <= 0, for no time limit
  31   */
  32  YAHOO.util.ImageLoader.group = function(trigEl, trigAct, timeout) {
  33      /**
  34       * Name for the group. Only used to identify the group in logging statements
  35       * @property name
  36       * @type String
  37       */
  38      this.name = 'unnamed';
  39      
  40      /**
  41       * Collection of images registered with this group
  42       * @property _imgObjs
  43       * @private
  44       * @type Object
  45       */
  46      this._imgObjs = {};
  47      
  48      /**
  49       * Timeout (time limit) length, in seconds
  50       * @property timeoutLen
  51       * @type Number
  52       */
  53      this.timeoutLen = timeout;
  54      
  55      /**
  56       * Timeout object to keep a handle on the time limit
  57       * @property _timeout
  58       * @private
  59       * @type Object
  60       */
  61      this._timeout = null;
  62      
  63      /**
  64       * Collection of triggers for this group.
  65       * Keeps track of each trigger's element, event, and event-listener-callback "fetch" function
  66       * @property _triggers
  67       * @private
  68       * @type Array
  69       */
  70      this._triggers = [];
  71  
  72      /**
  73       * Collection of custom-event triggers for this group.
  74       * Keeps track of each trigger's event object and event-listener-callback "fetch" function
  75       * @property _customTriggers
  76       * @private
  77       * @type Array
  78       */
  79      this._customTriggers = [];
  80  
  81      /**
  82       * Flag to check if images are above the fold. If foldConditional is true, the group will check each of its image locations at page load. If any part of the image is within the client viewport, the image is displayed immediately
  83       * @property foldConditional
  84       * @type Boolean
  85       */
  86      this.foldConditional = false;
  87  
  88      /**
  89       * Class name that will identify images belonging to the group. This class name will be removed from each element in order to fetch images.
  90       * This class should have, in its CSS style definition, "background:none !important;"
  91       * @property className
  92       * @type String
  93       */
  94      this.className = null;
  95  
  96      /**
  97       * HTML elements having the class name that is associated with this group
  98       * Elements are stored during the _foldCheck function and reused later during the fetch function. Gives a slight performance improvement when className and foldConditional are both used
  99       * @property _classImageEls
 100       * @private
 101       * @type Array
 102       */
 103      this._classImageEls = null;
 104  
 105      // add a listener to set the time limit on DOM ready
 106      // if DOM is already ready, do so immediately
 107      if (YAHOO.util.Event.DOMReady) {
 108          this._onloadTasks();
 109      }
 110      else {
 111          YAHOO.util.Event.onDOMReady(this._onloadTasks, this, true);
 112      }
 113  
 114      // add the trigger
 115      this.addTrigger(trigEl, trigAct);
 116  
 117  };
 118  
 119  /**
 120   * Adds a trigger to the group. Call this with the same style as YAHOO.util.Event.addListener
 121   * @method addTrigger
 122   * @param {String|HTMLElement} trigEl  The HTML element id or reference to assign the trigger event to
 123   * @param {String} trigAct The type of event to assign to trigEl
 124   */
 125  YAHOO.util.ImageLoader.group.prototype.addTrigger = function(trigEl, trigAct) {
 126      if (! trigEl || ! trigAct) {
 127          return;
 128      }
 129      /* Need to wrap the fetch function. Event Util can't distinguish prototyped functions of different instantiations
 130       *   Leads to this scenario: groupA and groupZ both have window-scroll triggers. groupZ also has a 2-sec timeout (groupA has no timeout).
 131       *   groupZ's timeout fires; we remove the triggers. The removeListener call finds the first window-scroll event with Y.u.IL.p.fetch, which is groupA's. 
 132       *   groupA's trigger is removed and never fires, leaving images unfetched
 133       */
 134      var wrappedFetch = function() {
 135          this.fetch();
 136      };
 137      this._triggers.push([trigEl, trigAct, wrappedFetch]);
 138      YAHOO.util.Event.addListener(trigEl, trigAct, wrappedFetch, this, true);
 139  };
 140  
 141  /**
 142   * Adds a custom event trigger to the group.
 143   * @method addCustomTrigger
 144   * @param {Object} event A YAHOO.util.CustomEvent object
 145   */
 146  YAHOO.util.ImageLoader.group.prototype.addCustomTrigger = function(event) {
 147      // make sure we're dealing with a CustomEvent object
 148      if (! event || ! event instanceof YAHOO.util.CustomEvent) {
 149          return;
 150      }
 151  
 152      // see comment in addTrigger()
 153      var wrappedFetch = function() {
 154          this.fetch();
 155      };
 156      this._customTriggers.push([event, wrappedFetch]);
 157      event.subscribe(wrappedFetch, this, true);
 158  };
 159  
 160  /**
 161   * Setup to do in the window's onload
 162   * Initiates time limit for group; executes the fold check for the images
 163   * @method _onloadTasks
 164   * @private
 165   */
 166  YAHOO.util.ImageLoader.group.prototype._onloadTasks = function() {
 167      if (this.timeoutLen && typeof(this.timeoutLen) == 'number' && this.timeoutLen > 0) {
 168          this._timeout = setTimeout(this._getFetchTimeout(), this.timeoutLen * 1000);
 169      }
 170  
 171      if (this.foldConditional) {
 172          this._foldCheck();
 173      }
 174  };
 175  
 176  /**
 177   * Returns the group's fetch method, with the proper closure, for use with setTimeout
 178   * @method _getFetchTimeout
 179   * @return {Function}  group's fetch method
 180   * @private
 181   */
 182  YAHOO.util.ImageLoader.group.prototype._getFetchTimeout = function() {
 183      var self = this;
 184      return function() { self.fetch(); };
 185  };
 186  
 187  /**
 188   * Registers a background image with the group
 189   * @method registerBgImage
 190   * @param {String}    domId    HTML DOM id of the image element
 191   * @param {String}    url    URL for the image
 192   * @return {Object}    bgImgObj that was registered, for modifying any attributes in the object
 193   */
 194  YAHOO.util.ImageLoader.group.prototype.registerBgImage = function(domId, url) {
 195      this._imgObjs[domId] = new YAHOO.util.ImageLoader.bgImgObj(domId, url);
 196      return this._imgObjs[domId];
 197  };
 198  /**
 199   * Registers a src image with the group
 200   * @method registerSrcImage
 201   * @param {String}    domId    HTML DOM id of the image element
 202   * @param {String}    url    URL for the image
 203   * @param {Int}    width    pixel width of the image - defaults to image's natural size
 204   * @param {Int}    height    pixel height of the image - defaults to image's natural size
 205   * @return {Object}    srcImgObj that was registered, for modifying any attributes in the object
 206   */
 207  YAHOO.util.ImageLoader.group.prototype.registerSrcImage = function(domId, url, width, height) {
 208      this._imgObjs[domId] = new YAHOO.util.ImageLoader.srcImgObj(domId, url, width, height);
 209      return this._imgObjs[domId];
 210  };
 211  /**
 212   * Registers an alpha-channel-type png background image with the group
 213   * @method registerPngBgImage
 214   * @param {String}    domId    HTML DOM id of the image element
 215   * @param {String}    url    URL for the image
 216   * @param {Object}  ailProps The AlphaImageLoader properties to be set for the image
 217   *                    Valid properties are 'sizingMethod' and 'enabled'
 218   * @return {Object}    pngBgImgObj that was registered, for modifying any attributes in the object
 219   */
 220  YAHOO.util.ImageLoader.group.prototype.registerPngBgImage = function(domId, url, ailProps) {
 221      this._imgObjs[domId] = new YAHOO.util.ImageLoader.pngBgImgObj(domId, url, ailProps);
 222      return this._imgObjs[domId];
 223  };
 224  
 225  /**
 226   * Displays the images in the group
 227   * @method fetch
 228   */
 229  YAHOO.util.ImageLoader.group.prototype.fetch = function() {
 230  
 231      var i, len, id;
 232  
 233      clearTimeout(this._timeout);
 234      // remove all listeners
 235      for (i=0, len = this._triggers.length; i < len; i++) {
 236          YAHOO.util.Event.removeListener(this._triggers[i][0], this._triggers[i][1], this._triggers[i][2]);
 237      }
 238      // remove custom event subscriptions
 239      for (i=0, len = this._customTriggers.length; i < len; i++) {
 240          this._customTriggers[i][0].unsubscribe(this._customTriggers[i][1], this);
 241      }
 242  
 243      // fetch whatever we need to by className
 244      this._fetchByClass();
 245  
 246      // fetch registered images
 247      for (id in this._imgObjs) {
 248          if (YAHOO.lang.hasOwnProperty(this._imgObjs, id)) {
 249              this._imgObjs[id].fetch();
 250          }
 251      }
 252  };
 253  
 254  /**
 255   * Checks the position of each image in the group. If any part of the image is within the client viewport, shows the image immediately.
 256   * @method _foldCheck
 257   * @private
 258   */
 259  YAHOO.util.ImageLoader.group.prototype._foldCheck = function() {
 260      var scrollTop = (document.compatMode != 'CSS1Compat') ? document.body.scrollTop : document.documentElement.scrollTop,
 261          viewHeight = YAHOO.util.Dom.getViewportHeight(),
 262          hLimit = scrollTop + viewHeight,
 263          scrollLeft = (document.compatMode != 'CSS1Compat') ? document.body.scrollLeft : document.documentElement.scrollLeft,
 264          viewWidth = YAHOO.util.Dom.getViewportWidth(),
 265          wLimit = scrollLeft + viewWidth,
 266              id, elPos, i, len;
 267      for (id in this._imgObjs) {
 268          if (YAHOO.lang.hasOwnProperty(this._imgObjs, id)) {
 269              elPos = YAHOO.util.Dom.getXY(this._imgObjs[id].domId);
 270              if (elPos[1] < hLimit && elPos[0] < wLimit) {
 271                  this._imgObjs[id].fetch();
 272              }
 273          }
 274      }
 275      // and by class
 276      if (this.className) {
 277          this._classImageEls = YAHOO.util.Dom.getElementsByClassName(this.className);
 278          for (i=0, len = this._classImageEls.length; i < len; i++) {
 279              elPos = YAHOO.util.Dom.getXY(this._classImageEls[i]);
 280              if (elPos[1] < hLimit && elPos[0] < wLimit) {
 281                  YAHOO.util.Dom.removeClass(this._classImageEls[i], this.className);
 282              }
 283          }
 284      }
 285  };
 286  
 287  /**
 288   * Finds all elements in the Dom with the class name specified in the group. Removes the class from the element in order to let the style definitions trigger the image fetching
 289   * @method _fetchByClass
 290   * @private
 291   */
 292  YAHOO.util.ImageLoader.group.prototype._fetchByClass = function() {
 293      if (! this.className) {
 294          return;
 295      }
 296  
 297      // this._classImageEls may have been set during _foldCheck
 298      if (this._classImageEls === null) {
 299          this._classImageEls = YAHOO.util.Dom.getElementsByClassName(this.className);
 300      }
 301      YAHOO.util.Dom.removeClass(this._classImageEls, this.className);
 302  };
 303  
 304  
 305  /**
 306   * Base class for image objects to be registered with the groups
 307   * @class YAHOO.util.ImageLoader.imgObj
 308   * @constructor
 309   * @param {String}    domId    HTML DOM id of the image element
 310   * @param {String}    url    URL for the image
 311   */
 312  YAHOO.util.ImageLoader.imgObj = function(domId, url) {
 313      /**
 314       * HTML DOM id of the image element
 315       * @property domId
 316       * @type String
 317       */
 318      this.domId = domId;
 319  
 320      /**
 321       * URL for the image
 322       * @property url
 323       * @type String
 324       */
 325      this.url = url;
 326  
 327      /**
 328       * Pixel width of the image. Will be set as a "width" attribute after the image is fetched.
 329       * Detaults to the natural width of the image.
 330       * Only appropriate with src images
 331       * @property width
 332       * @type Int
 333       */
 334      this.width = null;
 335  
 336      /**
 337       * Pixel height of the image. Will be set as a "height" attribute after the image is fetched.
 338       * Detaults to the natural height of the image.
 339       * Only appropriate with src images
 340       * @property height
 341       * @type Int
 342       */
 343      this.height = null;
 344  
 345      /**
 346       * Whether the style.visibility should be set to "visible" after the image is fetched.
 347       * Used when setting src images as visibility:hidden prior to image fetching
 348       * @property setVisible
 349       * @type Boolean
 350       */
 351      this.setVisible = false;
 352  
 353      /**
 354       * Whether the image has already been fetched. In the case of a foldCondional group, keeps track for when the trigger is fired so images aren't fetched twice
 355       * @property _fetched
 356       * @type Boolean
 357       * @private
 358       */
 359      this._fetched = false;
 360  };
 361  
 362  /**
 363   * Displays the image; puts the URL into the DOM
 364   * @method fetch
 365   */
 366  YAHOO.util.ImageLoader.imgObj.prototype.fetch = function() {
 367      if (this._fetched) {
 368          return;
 369      }
 370      var el = document.getElementById(this.domId);
 371      if (! el) {
 372          return;
 373      }
 374      this._applyUrl(el);
 375  
 376      if (this.setVisible) {
 377          el.style.visibility = 'visible';
 378      }
 379      if (this.width) {
 380          el.width = this.width;
 381      }
 382      if (this.height) {
 383          el.height = this.height;
 384      }
 385      this._fetched = true;
 386  };
 387  
 388  /**
 389   * Inserts the image URL into the DOM so that the image is displayed.
 390   * Must be overridden by child class
 391   * @method _applyUrl
 392   * @param {Object}    el    HTML DOM element
 393   * @private
 394   */
 395  YAHOO.util.ImageLoader.imgObj.prototype._applyUrl = function(el) {
 396  };
 397  
 398  /**
 399   * Background image object. A background image is one whose URL is specified by "background-image" in the element's style
 400   * @class YAHOO.util.ImageLoader.bgImgObj
 401   * @constructor
 402   * @extends YAHOO.util.ImageLoader.imgObj
 403   * @param {String}    domId    HTML DOM id of the image element
 404   * @param {String}    url    URL for the image
 405   */
 406  YAHOO.util.ImageLoader.bgImgObj = function(domId, url) {
 407      YAHOO.util.ImageLoader.bgImgObj.superclass.constructor.call(this, domId, url);
 408  };
 409  
 410  YAHOO.lang.extend(YAHOO.util.ImageLoader.bgImgObj, YAHOO.util.ImageLoader.imgObj);
 411  
 412  /**
 413   * Inserts the image URL into the DOM so that the image is displayed.
 414   * Sets style.backgroundImage
 415   * @method _applyUrl
 416   * @param {Object}    el    HTML DOM element
 417   * @private
 418   */
 419  YAHOO.util.ImageLoader.bgImgObj.prototype._applyUrl = function(el) {
 420      el.style.backgroundImage = "url('" + this.url + "')";
 421  };
 422  
 423  /**
 424   * Source image object. A source image is one whose URL is specified by a src attribute in the DOM element
 425   * @class YAHOO.util.ImageLoader.srcImgObj
 426   * @constructor
 427   * @extends YAHOO.util.ImageLoader.imgObj
 428   * @param {String}    domId    HTML DOM id of the image element
 429   * @param {String}    url    URL for the image
 430   * @param {Int}    width    pixel width of the image - defaults to image's natural size
 431   * @param {Int}    height    pixel height of the image - defaults to image's natural size
 432   */
 433  YAHOO.util.ImageLoader.srcImgObj = function(domId, url, width, height) {
 434      YAHOO.util.ImageLoader.srcImgObj.superclass.constructor.call(this, domId, url);
 435      this.width = width;
 436      this.height = height;
 437  };
 438  
 439  YAHOO.lang.extend(YAHOO.util.ImageLoader.srcImgObj, YAHOO.util.ImageLoader.imgObj);
 440  
 441  /**
 442   * Inserts the image URL into the DOM so that the image is displayed.
 443   * Sets src
 444   * @method _applyUrl
 445   * @param {Object}    el    HTML DOM element
 446   * @private
 447   */
 448  YAHOO.util.ImageLoader.srcImgObj.prototype._applyUrl = function(el) {
 449      el.src = this.url;
 450  };
 451  
 452  /**
 453   * PNG background image object. A PNG background image is one whose URL is specified through AlphaImageLoader or by "background-image" in the element's style
 454   * @class YAHOO.util.ImageLoader.pngBgImgObj
 455   * @constructor
 456   * @extends YAHOO.util.ImageLoader.imgObj
 457   * @param {String}    domId    HTML DOM id of the image element
 458   * @param {String}    url    URL for the image
 459   * @param {Object}  ailProps The AlphaImageLoader properties to be set for the image
 460   *                    Valid properties are 'sizingMethod' and 'enabled'
 461   */
 462  YAHOO.util.ImageLoader.pngBgImgObj = function(domId, url, ailProps) {
 463      YAHOO.util.ImageLoader.pngBgImgObj.superclass.constructor.call(this, domId, url);
 464  
 465      /**
 466       * AlphaImageLoader properties to be set for the image.
 467       * Valid properties are "sizingMethod" and "enabled".
 468       * @property props
 469       * @type Object
 470       */
 471      this.props = ailProps || {};
 472  };
 473  
 474  YAHOO.lang.extend(YAHOO.util.ImageLoader.pngBgImgObj, YAHOO.util.ImageLoader.imgObj);
 475  
 476  /**
 477   * Inserts the image URL into the DOM so that the image is displayed.
 478   * If the browser is determined to be IE6 (or older), sets the AlphaImageLoader src; otherwise sets style.backgroundImage
 479   * @method _applyUrl
 480   * @param {Object}    el    HTML DOM element
 481   * @private
 482   */
 483  YAHOO.util.ImageLoader.pngBgImgObj.prototype._applyUrl = function(el) {
 484      if (YAHOO.env.ua.ie && YAHOO.env.ua.ie <= 6) {
 485          var sizingMethod = (YAHOO.lang.isUndefined(this.props.sizingMethod)) ? 'scale' : this.props.sizingMethod,
 486              enabled = (YAHOO.lang.isUndefined(this.props.enabled)) ? 'true' : this.props.enabled;
 487          el.style.filter = 'progid:DXImageTransform.Microsoft.AlphaImageLoader(src="' + this.url + '", sizingMethod="' + sizingMethod + '", enabled="' + enabled + '")';
 488      }
 489      else {
 490          el.style.backgroundImage = "url('" + this.url + "')";
 491      }
 492  };
 493  YAHOO.register("imageloader", YAHOO.util.ImageLoader, {version: "2.9.0", build: "2800"});
 494  
 495  }, '2.9.0' ,{"requires": ["yui2-yahoo", "yui2-dom", "yui2-event"]});