1 /*

     2 Copyright (c) 2009, Yahoo! Inc. All rights reserved.

     3 Code licensed under the BSD License:

     4 http://developer.yahoo.net/yui/license.txt

     5 version: 3.0.0

     6 build: 1549

     7 */

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

     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  * @requires base-base, node-style, node-screen

    16  */

    17 

    18 

    19 	/**

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

    21 	 * @class ImgLoadGroup

    22 	 * @extends Base

    23 	 * @constructor

    24 	 */

    25 	Y.ImgLoadGroup = function() {

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

    27 		this._init();

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

    29 	};

    30 

    31 	Y.ImgLoadGroup.NAME = 'imgLoadGroup';

    32 

    33 	Y.ImgLoadGroup.ATTRS = {

    34 		

    35 		/**

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

    37 		 * @attribute name

    38 		 * @type String

    39 		 */

    40 		name: {

    41 			value: ''

    42 		},

    43 

    44 		/**

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

    46 		 * @attribute timeLimit

    47 		 * @type Number

    48 		 */

    49 		timeLimit: {

    50 			value: null

    51 		},

    52 

    53 		/**

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

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

    56 		 * @attribute foldDistance

    57 		 * @type Number

    58 		 */

    59 		foldDistance: {

    60 			validator: Y.Lang.isNumber,

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

    62 			lazyAdd: false

    63 		},

    64 

    65 		/**

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

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

    68 		 * @attribute className

    69 		 * @type String

    70 		 */

    71 		className: {

    72 			value: null,

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

    74 			lazyAdd: false

    75 		}

    76 

    77 	};

    78 

    79 	var groupProto = {

    80 

    81 		/**

    82 		 * Initialize all private members needed for the group.

    83 		 * @method _init

    84 		 * @private

    85 		 */

    86 		_init: function() {

    87 

    88 			/**

    89 			 * Collection of triggers for this group.

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

    91 			 * @property _triggers

    92 			 * @private

    93 			 * @type Array

    94 			 */

    95 			this._triggers = [];

    96 

    97 			/**

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

    99 			 * @property _imgObjs

   100 			 * @private

   101 			 * @type Object

   102 			 */

   103 			this._imgObjs = {};

   104 

   105 			/**

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

   107 			 * @property _timeout

   108 			 * @private

   109 			 * @type Object

   110 			 */

   111 			this._timeout = null;

   112 

   113 			/**

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

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

   116 			 * @property _classImageEls

   117 			 * @private

   118 			 * @type Array

   119 			 */

   120 			this._classImageEls = null;

   121 

   122 			/**

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

   124 			 * @property _className

   125 			 * @private

   126 			 * @type String

   127 			 */

   128 			this._className = null;

   129 

   130 			/**

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

   132 			 * @property _areFoldTriggersSet

   133 			 * @private

   134 			 * @type Boolean

   135 			 */

   136 			this._areFoldTriggersSet = false;

   137 

   138 			/**

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

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

   141 			 * @property _maxKnownHLimit

   142 			 * @private

   143 			 * @type Int

   144 			 */

   145 			this._maxKnownHLimit = 0;

   146 

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

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

   149 		},

   150 

   151 		/**

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

   153 		 * @method addTrigger

   154 		 * @chainable

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

   156 		 * @param {String} type  The event type

   157 		 */

   158 		addTrigger: function(obj, type) {

   159 			if (! obj || ! type) {

   160 				return this;

   161 			}

   162 

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

   164 

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

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

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

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

   169 			 */

   170 			var wrappedFetch = function() {

   171 				this.fetch();

   172 			};

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

   174 

   175 			return this;

   176 		},

   177 

   178 		/**

   179 		 * Adds a custom event trigger to the group.

   180 		 * @method addCustomTrigger

   181 		 * @chainable

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

   183 		 * @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

   184 		 */

   185 		addCustomTrigger: function(name, obj) {

   186 			if (! name) {

   187 				return this;

   188 			}

   189 

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

   191 

   192 			// see comment in addTrigger()

   193 			var wrappedFetch = function() {

   194 				this.fetch();

   195 			};

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

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

   198 			}

   199 			else {

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

   201 			}

   202 

   203 			return this;

   204 		},

   205 

   206 		/**

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

   208 		 * @method _setFoldTriggers

   209 		 * @private

   210 		 */

   211 		_setFoldTriggers: function() {

   212 			if (this._areFoldTriggersSet) {

   213 				return;

   214 			}

   215 

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

   217 

   218 			var wrappedFoldCheck = function() {

   219 				this._foldCheck();

   220 			};

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

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

   223 			this._areFoldTriggersSet = true;

   224 		},

   225 

   226 		/**

   227 		 * Performs necessary setup at domready time.

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

   229 		 * @method _onloadTasks

   230 		 * @private

   231 		 */

   232 		_onloadTasks: function() {

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

   234 			if (timeLim && timeLim > 0) {

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

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

   237 			}

   238 

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

   240 				this._foldCheck();

   241 			}

   242 		},

   243 

   244 		/**

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

   246 		 * @method _getFetchTimeout

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

   248 		 * @private

   249 		 */

   250 		_getFetchTimeout: function() {

   251 			var self = this;

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

   253 		},

   254 

   255 		/**

   256 		 * Registers an image with the group.

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

   258 		 * @method registerImage

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

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

   261 		 */

   262 		registerImage: function() {

   263 			var domId = arguments[0].domId;

   264 			if (! domId) {

   265 				return null;

   266 			}

   267 

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

   269 

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

   271 			return this._imgObjs[domId];

   272 		},

   273 

   274 		/**

   275 		 * Displays the images in the group.

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

   277 		 * @method fetch

   278 		 */

   279 		fetch: function() {

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

   281 

   282 			// done with the triggers

   283 			this._clearTriggers();

   284 

   285 			// fetch whatever we need to by className

   286 			this._fetchByClass();

   287 

   288 			// fetch registered images

   289 			for (var id in this._imgObjs) {

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

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

   292 				}

   293 			}

   294 		},

   295 

   296 		/**

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

   298 		 * @method _clearTriggers

   299 		 * @private

   300 		 */

   301 		_clearTriggers: function() {

   302 			clearTimeout(this._timeout);

   303 			// detach all listeners

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

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

   306 			}

   307 		},

   308 

   309 		/**

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

   311 		 * @method _foldCheck

   312 		 * @private

   313 		 */

   314 		_foldCheck: function() {

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

   316 

   317 			var allFetched = true,

   318 			    viewReg = Y.DOM.viewportRegion(),

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

   320 					id, imgFetched, els, i, len;

   321 

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

   323 			if (hLimit <= this._maxKnownHLimit) {

   324 				return;

   325 			}

   326 			this._maxKnownHLimit = hLimit;

   327 

   328 			for (id in this._imgObjs) {

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

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

   331 					allFetched = allFetched && imgFetched;

   332 				}

   333 			}

   334 

   335 			// and by class

   336 			if (this._className) {

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

   338 					// get all the relevant elements and store them

   339 					this._classImageEls = [];

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

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

   342 				}

   343 				els = this._classImageEls;

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

   345 					if (els[i].fetched) {

   346 						continue;

   347 					}

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

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

   350 						els[i].fetched = true;

   351 						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');

   352 					}

   353 					else {

   354 						allFetched = false;

   355 					}

   356 				}

   357 			}

   358 			

   359 			// if allFetched, remove listeners

   360 			if (allFetched) {

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

   362 				this._clearTriggers();

   363 			}

   364 		},

   365 

   366 		/**

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

   368 		 * @method _fetchByClass

   369 		 * @private

   370 		 */

   371 		_fetchByClass: function() {

   372 			if (! this._className) {

   373 				return;

   374 			}

   375 

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

   377 

   378 			Y.all('.' + this._className).removeClass(this._className);

   379 		}

   380 

   381 	};

   382 

   383 

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

   385 

   386 

   387 	//------------------------------------------------

   388 

   389 

   390 	/**

   391 	 * Image objects to be registered with the groups

   392 	 * @class ImgLoadImgObj

   393 	 * @extends Base

   394 	 * @constructor

   395 	 */

   396 	Y.ImgLoadImgObj = function() {

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

   398 		this._init();

   399 	};

   400 		

   401 	Y.ImgLoadImgObj.NAME = 'imgLoadImgObj';

   402 

   403 	Y.ImgLoadImgObj.ATTRS = {

   404 		/**

   405 		 * HTML DOM id of the image element.

   406 		 * @attribute domId

   407 		 * @type String

   408 		 */

   409 		domId: {

   410 			value: null,

   411 			writeOnce: true

   412 		},

   413 

   414 		/**

   415 		 * Background URL for the image.

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

   417 		 * @attribute bgUrl

   418 		 * @type String

   419 		 */

   420 		bgUrl: {

   421 			value: null

   422 		},

   423 

   424 		/**

   425 		 * Source URL for the image.

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

   427 		 * @attribute srcUrl

   428 		 * @type String

   429 		 */

   430 		srcUrl: {

   431 			value: null

   432 		},

   433 

   434 		/**

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

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

   437 		 * Usually only used with src images.

   438 		 * @attribute width

   439 		 * @type Int

   440 		 */

   441 		width: {

   442 			value: null

   443 		},

   444 

   445 		/**

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

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

   448 		 * Usually only used with src images.

   449 		 * @attribute height

   450 		 * @type Int

   451 		 */

   452 		height: {

   453 			value: null

   454 		},

   455 

   456 		/**

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

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

   459 		 * @attribute setVisible

   460 		 * @type Boolean

   461 		 */

   462 		setVisible: {

   463 			value: false

   464 		},

   465 

   466 		/**

   467 		 * Whether the image is a PNG.

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

   469 		 * Only used with background images.

   470 		 * @attribute isPng

   471 		 * @type Boolean

   472 		 */

   473 		isPng: {

   474 			value: false

   475 		},

   476 

   477 		/**

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

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

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

   481 		 * @attribute sizingMethod

   482 		 * @type String

   483 		 */

   484 		sizingMethod: {

   485 			value: 'scale'

   486 		},

   487 

   488 		/**

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

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

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

   492 		 * @attribute enabled

   493 		 * @type String

   494 		 */

   495 		enabled: {

   496 			value: 'true'

   497 		}

   498 

   499 	};

   500 

   501 	var imgProto = {

   502 

   503 		/**

   504 		 * Initialize all private members needed for the group.

   505 		 * @method _init

   506 		 * @private

   507 		 */

   508 		_init: function() {

   509 

   510 			/**

   511 			 * Whether this image has already been fetched.

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

   513 			 * @property _fetched

   514 			 * @private

   515 			 * @type Boolean

   516 			 */

   517 			this._fetched = false;

   518 

   519 			/**

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

   521 			 * @property _imgEl

   522 			 * @private

   523 			 * @type Object

   524 			 */

   525 			this._imgEl = null;

   526 

   527 			/**

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

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

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

   531 			 * @property _yPos

   532 			 * @private

   533 			 * @type Int

   534 			 */

   535 			this._yPos = null;

   536 		},

   537 

   538 		/**

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

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

   541 		 * @method fetch

   542 		 * @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

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

   544 		 */

   545 		fetch: function(withinY) {

   546 			if (this._fetched) {

   547 				return true;

   548 			}

   549 

   550 			var el = this._getImgEl(),

   551 			    yPos;

   552 			if (! el) {

   553 				return false;

   554 			}

   555 

   556 			if (withinY) {

   557 				// need a distance check

   558 				yPos = this._getYPos();

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

   560 					return false;

   561 				}

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

   563 			}

   564 

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

   566 

   567 			// apply url

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

   569 				// bg url

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

   571 					// png for which to apply AlphaImageLoader

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

   573 				}

   574 				else {

   575 					// regular bg image

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

   577 				}

   578 			}

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

   580 				// regular src image

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

   582 			}

   583 

   584 			// apply attributes

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

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

   587 			}

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

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

   590 			}

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

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

   593 			}

   594 

   595 			this._fetched = true;

   596 

   597 			return true;

   598 		},

   599 

   600 		/**

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

   602 		 * @method _getImgEl

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

   604 		 * @private

   605 		 */

   606 		_getImgEl: function() {

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

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

   609 			}

   610 			return this._imgEl;

   611 		},

   612 

   613 		/**

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

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

   616 		 * @method _getYPos

   617 		 * @returns {Object} The Y position of the image

   618 		 * @private

   619 		 */

   620 		_getYPos: function() {

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

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

   623 			}

   624 			return this._yPos;

   625 		}

   626 

   627 	};

   628 

   629 

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

   631 

   632 

   633 

   634 

   635 }, '3.0.0' ,{requires:['base-base', 'node-style', 'node-screen']});