1 /*

     2 YUI 3.10.3 (build 2fb5187)

     3 Copyright 2013 Yahoo! Inc. All rights reserved.

     4 Licensed under the BSD License.

     5 http://yuilibrary.com/license/

     6 */

     7 

     8 YUI.add('imageloader', function (Y, NAME) {

     9 

    10 /**

    11  * The ImageLoader Utility is a framework to dynamically load images according to certain triggers,

    12  * enabling faster load times and a more responsive UI.

    13  *

    14  * @module imageloader

    15  */

    16 

    17 

    18 	/**

    19 	 * 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.

    20 	 * @class ImgLoadGroup

    21 	 * @extends Base

    22 	 * @constructor

    23 	 */

    24 	Y.ImgLoadGroup = function() {

    25 		// call init first, because it sets up local vars for storing attribute-related info

    26 		this._init();

    27 		Y.ImgLoadGroup.superclass.constructor.apply(this, arguments);

    28 	};

    29 

    30 	Y.ImgLoadGroup.NAME = 'imgLoadGroup';

    31 

    32 	Y.ImgLoadGroup.ATTRS = {

    33 		

    34 		/**

    35 		 * Name for the group. Only used to identify the group in logging statements.

    36 		 * @attribute name

    37 		 * @type String

    38 		 */

    39 		name: {

    40 			value: ''

    41 		},

    42 

    43 		/**

    44 		 * Time limit, in seconds, after which images are fetched regardless of trigger events.

    45 		 * @attribute timeLimit

    46 		 * @type Number

    47 		 */

    48 		timeLimit: {

    49 			value: null

    50 		},

    51 

    52 		/**

    53 		 * Distance below the fold for which images are loaded. Images are not loaded until they are at most this distance away from (or above) the fold.

    54 		 * This check is performed at page load (domready) and after any window scroll or window resize event (until all images are loaded).

    55 		 * @attribute foldDistance

    56 		 * @type Number

    57 		 */

    58 		foldDistance: {

    59 			validator: Y.Lang.isNumber,

    60 			setter: function(val) { this._setFoldTriggers(); return val; },

    61 			lazyAdd: false

    62 		},

    63 

    64 		/**

    65 		 * Class name that will identify images belonging to the group. This class name will be removed from each element in order to fetch images.

    66 		 * This class should have, in its CSS style definition, "<code>background:none !important;</code>".

    67 		 * @attribute className

    68 		 * @type String

    69 		 */

    70 		className: {

    71 			value: null,

    72 			setter: function(name) { this._className = name; return name; },

    73 			lazyAdd: false

    74 		}, 

    75         

    76         /**

    77          * Determines how to act when className is used as the way to delay load images. The "default" action is to just

    78          * remove the class name. The "enhanced" action is to remove the class name and also set the src attribute if

    79          * the element is an img.

    80          * @attribute classNameAction

    81          * @type String

    82          */

    83         classNameAction: {

    84             value: "default"

    85         }

    86 

    87 	};

    88 

    89 	var groupProto = {

    90 

    91 		/**

    92 		 * Initialize all private members needed for the group.

    93 		 * @method _init

    94 		 * @private

    95 		 */

    96 		_init: function() {

    97 

    98 			/**

    99 			 * Collection of triggers for this group.

   100 			 * Keeps track of each trigger's event handle, as returned from <code>Y.on</code>.

   101 			 * @property _triggers

   102 			 * @private

   103 			 * @type Array

   104 			 */

   105 			this._triggers = [];

   106 

   107 			/**

   108 			 * Collection of images (<code>Y.ImgLoadImgObj</code> objects) registered with this group, keyed by DOM id.

   109 			 * @property _imgObjs

   110 			 * @private

   111 			 * @type Object

   112 			 */

   113 			this._imgObjs = {};

   114 

   115 			/**

   116 			 * Timeout object to keep a handle on the time limit.

   117 			 * @property _timeout

   118 			 * @private

   119 			 * @type Object

   120 			 */

   121 			this._timeout = null;

   122 

   123 			/**

   124 			 * DOM elements having the class name that is associated with this group.

   125 			 * Elements are stored during the <code>_foldCheck</code> function and reused later during any subsequent <code>_foldCheck</code> calls - gives a slight performance improvement when the page fold is repeatedly checked.

   126 			 * @property _classImageEls

   127 			 * @private

   128 			 * @type Array

   129 			 */

   130 			this._classImageEls = null;

   131 

   132 			/**

   133 			 * Keep the CSS class name in a member variable for ease and speed.

   134 			 * @property _className

   135 			 * @private

   136 			 * @type String

   137 			 */

   138 			this._className = null;

   139 

   140 			/**

   141 			 * Boolean tracking whether the window scroll and window resize triggers have been set if this is a fold group.

   142 			 * @property _areFoldTriggersSet

   143 			 * @private

   144 			 * @type Boolean

   145 			 */

   146 			this._areFoldTriggersSet = false;

   147 

   148 			/**

   149 			 * The maximum pixel height of the document that has been made visible.

   150 			 * During fold checks, if the user scrolls up then there's no need to check for newly exposed images.

   151 			 * @property _maxKnownHLimit

   152 			 * @private

   153 			 * @type Int

   154 			 */

   155 			this._maxKnownHLimit = 0;

   156 

   157 			// add a listener to domready that will start the time limit

   158 			Y.on('domready', this._onloadTasks, this);

   159 		},

   160 

   161 		/**

   162 		 * Adds a trigger to the group. Arguments are passed to <code>Y.on</code>.

   163 		 * @method addTrigger

   164 		 * @chainable

   165 		 * @param {Object} obj  The DOM object to attach the trigger event to

   166 		 * @param {String} type  The event type

   167 		 */

   168 		addTrigger: function(obj, type) {

   169 			if (! obj || ! type) {

   170 				return this;

   171 			}

   172 

   173 			Y.log('adding trigger to group: ' + this.get('name'), 'info', 'imageloader');

   174 

   175 			/* Need to wrap the fetch function. Event Util can't distinguish prototyped functions of different instantiations.

   176 			 *   Leads to this scenario: groupA and groupZ both have window-scroll triggers. groupZ also has a 2-sec timeout (groupA has no timeout).

   177 			 *   groupZ's timeout fires; we remove the triggers. The detach call finds the first window-scroll event with Y.ILG.p.fetch, which is groupA's. 

   178 			 *   groupA's trigger is removed and never fires, leaving images unfetched.

   179 			 */

   180 			var wrappedFetch = function() {

   181 				this.fetch();

   182 			};

   183 			this._triggers.push( Y.on(type, wrappedFetch, obj, this) );

   184 

   185 			return this;

   186 		},

   187 

   188 		/**

   189 		 * Adds a custom event trigger to the group.

   190 		 * @method addCustomTrigger

   191 		 * @chainable

   192 		 * @param {String} name  The name of the event

   193 		 * @param {Object} obj  The object on which to attach the event. <code>obj</code> is optional - by default the event is attached to the <code>Y</code> instance

   194 		 */

   195 		addCustomTrigger: function(name, obj) {

   196 			if (! name) {

   197 				return this;

   198 			}

   199 

   200 			Y.log('adding custom trigger to group: ' + this.get('name'), 'info', 'imageloader');

   201 

   202 			// see comment in addTrigger()

   203 			var wrappedFetch = function() {

   204 				this.fetch();

   205 			};

   206 			if (Y.Lang.isUndefined(obj)) {

   207 				this._triggers.push( Y.on(name, wrappedFetch, this) );

   208 			}

   209 			else {

   210 				this._triggers.push( obj.on(name, wrappedFetch, this) );

   211 			}

   212 

   213 			return this;

   214 		},

   215 

   216 		/**

   217 		 * Sets the window scroll and window resize triggers for any group that is fold-conditional (i.e., has a fold distance set).

   218 		 * @method _setFoldTriggers

   219 		 * @private

   220 		 */

   221 		_setFoldTriggers: function() {

   222 			if (this._areFoldTriggersSet) {

   223 				return;

   224 			}

   225 

   226 			Y.log('setting window scroll and resize events for group: ' + this.get('name'), 'info', 'imageloader');

   227 

   228 			var wrappedFoldCheck = function() {

   229 				this._foldCheck();

   230 			};

   231 			this._triggers.push( Y.on('scroll', wrappedFoldCheck, window, this) );

   232 			this._triggers.push( Y.on('resize', wrappedFoldCheck, window, this) );

   233 			this._areFoldTriggersSet = true;

   234 		},

   235 

   236 		/**

   237 		 * Performs necessary setup at domready time.

   238 		 * Initiates time limit for group; executes the fold check for the images.

   239 		 * @method _onloadTasks

   240 		 * @private

   241 		 */

   242 		_onloadTasks: function() {

   243 			var timeLim = this.get('timeLimit');

   244 			if (timeLim && timeLim > 0) {

   245 				Y.log('setting time limit of ' + timeLim + ' seconds for group: ' + this.get('name'), 'info', 'imageloader');

   246 				this._timeout = setTimeout(this._getFetchTimeout(), timeLim * 1000);

   247 			}

   248 

   249 			if (! Y.Lang.isUndefined(this.get('foldDistance'))) {

   250 				this._foldCheck();

   251 			}

   252 		},

   253 

   254 		/**

   255 		 * Returns the group's <code>fetch</code> method, with the proper closure, for use with <code>setTimeout</code>.

   256 		 * @method _getFetchTimeout

   257 		 * @return {Function}  group's <code>fetch</code> method

   258 		 * @private

   259 		 */

   260 		_getFetchTimeout: function() {

   261 			var self = this;

   262 			return function() { self.fetch(); };

   263 		},

   264 

   265 		/**

   266 		 * Registers an image with the group.

   267 		 * Arguments are passed through to a <code>Y.ImgLoadImgObj</code> constructor; see that class' attribute documentation for detailed information. "<code>domId</code>" is a required attribute.

   268 		 * @method registerImage

   269 		 * @param {Object} *  A configuration object literal with attribute name/value pairs  (passed through to a <code>Y.ImgLoadImgObj</code> constructor)

   270 		 * @return {Object}  <code>Y.ImgLoadImgObj</code> that was registered

   271 		 */

   272 		registerImage: function() {

   273 			var domId = arguments[0].domId;

   274 			if (! domId) {

   275 				return null;

   276 			}

   277 

   278 			Y.log('adding image with id: ' + domId + ' to group: ' + this.get('name'), 'info', 'imageloader');

   279 

   280 			this._imgObjs[domId] = new Y.ImgLoadImgObj(arguments[0]);

   281 			return this._imgObjs[domId];

   282 		},

   283 

   284 		/**

   285 		 * Displays the images in the group.

   286 		 * This method is called when a trigger fires or the time limit expires; it shouldn't be called externally, but is not private in the rare event that it needs to be called immediately.

   287 		 * @method fetch

   288 		 */

   289 		fetch: function() {

   290 			Y.log('Fetching images in group: "' + this.get('name') + '".', 'info', 'imageloader');

   291 

   292 			// done with the triggers

   293 			this._clearTriggers();

   294 

   295 			// fetch whatever we need to by className

   296 			this._fetchByClass();

   297 

   298 			// fetch registered images

   299 			for (var id in this._imgObjs) {

   300 				if (this._imgObjs.hasOwnProperty(id)) {

   301 					this._imgObjs[id].fetch();

   302 				}

   303 			}

   304 		},

   305 

   306 		/**

   307 		 * Clears the timeout and all triggers associated with the group.

   308 		 * @method _clearTriggers

   309 		 * @private

   310 		 */

   311 		_clearTriggers: function() {

   312 			clearTimeout(this._timeout);

   313 			// detach all listeners

   314 			for (var i=0, len = this._triggers.length; i < len; i++) {

   315 				this._triggers[i].detach();

   316 			}

   317 		},

   318 

   319 		/**

   320 		 * Checks the position of each image in the group. If any part of the image is within the specified distance (<code>foldDistance</code>) of the client viewport, the image is fetched immediately.

   321 		 * @method _foldCheck

   322 		 * @private

   323 		 */

   324 		_foldCheck: function() {

   325 			Y.log('Checking for images above the fold in group: "' + this.get('name') + '"', 'info', 'imageloader');

   326 

   327 			var allFetched = true,

   328 			    viewReg = Y.DOM.viewportRegion(),

   329 			    hLimit = viewReg.bottom + this.get('foldDistance'),

   330 					id, imgFetched, els, i, len;

   331 

   332 			// unless we've uncovered new frontiers, there's no need to continue

   333 			if (hLimit <= this._maxKnownHLimit) {

   334 				return;

   335 			}

   336 			this._maxKnownHLimit = hLimit;

   337 

   338 			for (id in this._imgObjs) {

   339 				if (this._imgObjs.hasOwnProperty(id)) {

   340 					imgFetched = this._imgObjs[id].fetch(hLimit);

   341 					allFetched = allFetched && imgFetched;

   342 				}

   343 			}

   344 

   345 			// and by class

   346 			if (this._className) {

   347 				if (this._classImageEls === null) {

   348 					// get all the relevant elements and store them

   349 					this._classImageEls = [];

   350 					els = Y.all('.' + this._className);

   351 					els.each( function(node) { this._classImageEls.push( { el: node, y: node.getY(), fetched: false } ); }, this);

   352 				}

   353 				els = this._classImageEls;

   354 				for (i=0, len = els.length; i < len; i++) {

   355 					if (els[i].fetched) {

   356 						continue;

   357 					}

   358 					if (els[i].y && els[i].y <= hLimit) {

   359 						//els[i].el.removeClass(this._className);

   360 						this._updateNodeClassName(els[i].el);

   361                         els[i].fetched = true;

   362 						Y.log('Image with id "' + els[i].el.get('id') + '" is within distance of the fold. Fetching image. (Image registered by class name with the group - may not have an id.)', 'info', 'imageloader');

   363 					}

   364 					else {

   365 						allFetched = false;

   366 					}

   367 				}

   368 			}

   369 			

   370 			// if allFetched, remove listeners

   371 			if (allFetched) {

   372 				Y.log('All images fetched; removing listeners for group: "' + this.get('name') + '"', 'info', 'imageloader');

   373 				this._clearTriggers();

   374 			}

   375 		},

   376         

   377         /**

   378          * Updates a given node, removing the ImageLoader class name. If the

   379          * node is an img and the classNameAction is "enhanced", then node

   380          * class name is removed and also the src attribute is set to the 

   381          * image URL as well as clearing the style background image.

   382          * @method _updateNodeClassName

   383          * @param node {Node} The node to act on.

   384          * @private

   385          */

   386         _updateNodeClassName: function(node){

   387             var url;

   388             

   389             if (this.get("classNameAction") == "enhanced"){

   390                 

   391                 if (node.get("tagName").toLowerCase() == "img"){

   392                     url = node.getStyle("backgroundImage");

   393                     /url\(["']?(.*?)["']?\)/.test(url);

   394                     url = RegExp.$1;

   395                     node.set("src", url);

   396                     node.setStyle("backgroundImage", "");

   397                 }

   398             }

   399             

   400             node.removeClass(this._className);        

   401         },

   402 

   403 		/**

   404 		 * 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.

   405 		 * @method _fetchByClass

   406 		 * @private

   407 		 */

   408 		_fetchByClass: function() {

   409 			if (! this._className) {

   410 				return;

   411 			}

   412 

   413 			Y.log('Fetching all images with class "' + this._className + '" in group "' + this.get('name') + '".', 'info', 'imageloader');

   414 

   415 			Y.all('.' + this._className).each(Y.bind(this._updateNodeClassName, this));

   416 		}

   417 

   418 	};

   419 

   420 

   421 	Y.extend(Y.ImgLoadGroup, Y.Base, groupProto);

   422 

   423 

   424 	//------------------------------------------------

   425 

   426 

   427 	/**

   428 	 * Image objects to be registered with the groups

   429 	 * @class ImgLoadImgObj

   430 	 * @extends Base

   431 	 * @constructor

   432 	 */

   433 	Y.ImgLoadImgObj = function() {

   434 		Y.ImgLoadImgObj.superclass.constructor.apply(this, arguments);

   435 		this._init();

   436 	};

   437 		

   438 	Y.ImgLoadImgObj.NAME = 'imgLoadImgObj';

   439 

   440 	Y.ImgLoadImgObj.ATTRS = {

   441 		/**

   442 		 * HTML DOM id of the image element.

   443 		 * @attribute domId

   444 		 * @type String

   445 		 */

   446 		domId: {

   447 			value: null,

   448 			writeOnce: true

   449 		},

   450 

   451 		/**

   452 		 * Background URL for the image.

   453 		 * For an image whose URL is specified by "<code>background-image</code>" in the element's style.

   454 		 * @attribute bgUrl

   455 		 * @type String

   456 		 */

   457 		bgUrl: {

   458 			value: null

   459 		},

   460 

   461 		/**

   462 		 * Source URL for the image.

   463 		 * For an image whose URL is specified by a "<code>src</code>" attribute in the DOM element.

   464 		 * @attribute srcUrl

   465 		 * @type String

   466 		 */

   467 		srcUrl: {

   468 			value: null

   469 		},

   470 

   471 		/**

   472 		 * Pixel width of the image. Will be set as a <code>width</code> attribute on the DOM element after the image is fetched.

   473 		 * Defaults to the natural width of the image (no <code>width</code> attribute will be set).

   474 		 * Usually only used with src images.

   475 		 * @attribute width

   476 		 * @type Int

   477 		 */

   478 		width: {

   479 			value: null

   480 		},

   481 

   482 		/**

   483 		 * Pixel height of the image. Will be set as a <code>height</code> attribute on the DOM element after the image is fetched.

   484 		 * Defaults to the natural height of the image (no <code>height</code> attribute will be set).

   485 		 * Usually only used with src images.

   486 		 * @attribute height

   487 		 * @type Int

   488 		 */

   489 		height: {

   490 			value: null

   491 		},

   492 

   493 		/**

   494 		 * Whether the image's <code>style.visibility</code> should be set to <code>visible</code> after the image is fetched.

   495 		 * Used when setting images as <code>visibility:hidden</code> prior to image fetching.

   496 		 * @attribute setVisible

   497 		 * @type Boolean

   498 		 */

   499 		setVisible: {

   500 			value: false

   501 		},

   502 

   503 		/**

   504 		 * Whether the image is a PNG.

   505 		 * PNG images get special treatment in that the URL is specified through AlphaImageLoader for IE, versions 6 and earlier.

   506 		 * Only used with background images.

   507 		 * @attribute isPng

   508 		 * @type Boolean

   509 		 */

   510 		isPng: {

   511 			value: false

   512 		},

   513 

   514 		/**

   515 		 * AlphaImageLoader <code>sizingMethod</code> property to be set for the image.

   516 		 * Only set if <code>isPng</code> value for this image is set to <code>true</code>.

   517 		 * Defaults to <code>scale</code>.

   518 		 * @attribute sizingMethod

   519 		 * @type String

   520 		 */

   521 		sizingMethod: {

   522 			value: 'scale'

   523 		},

   524 

   525 		/**

   526 		 * AlphaImageLoader <code>enabled</code> property to be set for the image.

   527 		 * Only set if <code>isPng</code> value for this image is set to <code>true</code>.

   528 		 * Defaults to <code>true</code>.

   529 		 * @attribute enabled

   530 		 * @type String

   531 		 */

   532 		enabled: {

   533 			value: 'true'

   534 		}

   535 

   536 	};

   537 

   538 	var imgProto = {

   539 

   540 		/**

   541 		 * Initialize all private members needed for the group.

   542 		 * @method _init

   543 		 * @private

   544 		 */

   545 		_init: function() {

   546 

   547 			/**

   548 			 * Whether this image has already been fetched.

   549 			 * In the case of fold-conditional groups, images won't be fetched twice.

   550 			 * @property _fetched

   551 			 * @private

   552 			 * @type Boolean

   553 			 */

   554 			this._fetched = false;

   555 

   556 			/**

   557 			 * The Node object returned from <code>Y.one</code>, to avoid repeat calls to access the DOM.

   558 			 * @property _imgEl

   559 			 * @private

   560 			 * @type Object

   561 			 */

   562 			this._imgEl = null;

   563 

   564 			/**

   565 			 * The vertical position returned from <code>getY</code>, to avoid repeat calls to access the DOM.

   566 			 * The Y position is checked only for images registered with fold-conditional groups. The position is checked first at page load (domready)

   567 			 *   and this caching enhancement assumes that the image's vertical position won't change after that first check.

   568 			 * @property _yPos

   569 			 * @private

   570 			 * @type Int

   571 			 */

   572 			this._yPos = null;

   573 		},

   574 

   575 		/**

   576 		 * Displays the image; puts the URL into the DOM.

   577 		 * This method shouldn't be called externally, but is not private in the rare event that it needs to be called immediately.

   578 		 * @method fetch

   579 		 * @param {Int} withinY  The pixel distance from the top of the page, for which if the image lies within, it will be fetched. Undefined indicates that no check should be made, and the image should always be fetched

   580 		 * @return {Boolean}  Whether the image has been fetched (either during this execution or previously)

   581 		 */

   582 		fetch: function(withinY) {

   583 			if (this._fetched) {

   584 				return true;

   585 			}

   586 

   587 			var el = this._getImgEl(),

   588 			    yPos;

   589 			if (! el) {

   590 				return false;

   591 			}

   592 

   593 			if (withinY) {

   594 				// need a distance check

   595 				yPos = this._getYPos();

   596 				if (! yPos || yPos > withinY) {

   597 					return false;

   598 				}

   599 				Y.log('Image with id "' + this.get('domId') + '" is within distance of the fold. Fetching image.', 'info', 'imageloader');

   600 			}

   601 

   602 			Y.log('Fetching image with id "' + this.get('domId') + '".', 'info', 'imageloader');

   603 

   604 			// apply url

   605 			if (this.get('bgUrl') !== null) {

   606 				// bg url

   607 				if (this.get('isPng') && Y.UA.ie && Y.UA.ie <= 6) {

   608 					// png for which to apply AlphaImageLoader

   609 					el.setStyle('filter', 'progid:DXImageTransform.Microsoft.AlphaImageLoader(src="' + this.get('bgUrl') + '", sizingMethod="' + this.get('sizingMethod') + '", enabled="' + this.get('enabled') + '")');

   610 				}

   611 				else {

   612 					// regular bg image

   613 					el.setStyle('backgroundImage', "url('" + this.get('bgUrl') + "')");

   614 				}

   615 			}

   616 			else if (this.get('srcUrl') !== null) {

   617 				// regular src image

   618 				el.setAttribute('src', this.get('srcUrl'));

   619 			}

   620 

   621 			// apply attributes

   622 			if (this.get('setVisible')) {

   623 				el.setStyle('visibility', 'visible');

   624 			}

   625 			if (this.get('width')) {

   626 				el.setAttribute('width', this.get('width'));

   627 			}

   628 			if (this.get('height')) {

   629 				el.setAttribute('height', this.get('height'));

   630 			}

   631 

   632 			this._fetched = true;

   633 

   634 			return true;

   635 		},

   636 

   637 		/**

   638 		 * Gets the object (as a <code>Y.Node</code>) of the DOM element indicated by "<code>domId</code>".

   639 		 * @method _getImgEl

   640 		 * @return {Object} DOM element of the image as a <code>Y.Node</code> object

   641 		 * @private

   642 		 */

   643 		_getImgEl: function() {

   644 			if (this._imgEl === null) {

   645 				this._imgEl = Y.one('#' + this.get('domId'));

   646 			}

   647 			return this._imgEl;

   648 		},

   649 

   650 		/**

   651 		 * Gets the Y position of the node in page coordinates.

   652 		 * Expects that the page-coordinate position of the image won't change.

   653 		 * @method _getYPos

   654 		 * @return {Object} The Y position of the image

   655 		 * @private

   656 		 */

   657 		_getYPos: function() {

   658 			if (this._yPos === null) {

   659 				this._yPos = this._getImgEl().getY();

   660 			}

   661 			return this._yPos;

   662 		}

   663 

   664 	};

   665 

   666 

   667 	Y.extend(Y.ImgLoadImgObj, Y.Base, imgProto);

   668 

   669 

   670 

   671 

   672 }, '3.10.3', {"requires": ["base-base", "node-style", "node-screen"]});