|
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 |
|
174 /* Need to wrap the fetch function. Event Util can't distinguish prototyped functions of different instantiations. |
|
175 * Leads to this scenario: groupA and groupZ both have window-scroll triggers. groupZ also has a 2-sec timeout (groupA has no timeout). |
|
176 * 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. |
|
177 * groupA's trigger is removed and never fires, leaving images unfetched. |
|
178 */ |
|
179 var wrappedFetch = function() { |
|
180 this.fetch(); |
|
181 }; |
|
182 this._triggers.push( Y.on(type, wrappedFetch, obj, this) ); |
|
183 |
|
184 return this; |
|
185 }, |
|
186 |
|
187 /** |
|
188 * Adds a custom event trigger to the group. |
|
189 * @method addCustomTrigger |
|
190 * @chainable |
|
191 * @param {String} name The name of the event |
|
192 * @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 |
|
193 */ |
|
194 addCustomTrigger: function(name, obj) { |
|
195 if (! name) { |
|
196 return this; |
|
197 } |
|
198 |
|
199 |
|
200 // see comment in addTrigger() |
|
201 var wrappedFetch = function() { |
|
202 this.fetch(); |
|
203 }; |
|
204 if (Y.Lang.isUndefined(obj)) { |
|
205 this._triggers.push( Y.on(name, wrappedFetch, this) ); |
|
206 } |
|
207 else { |
|
208 this._triggers.push( obj.on(name, wrappedFetch, this) ); |
|
209 } |
|
210 |
|
211 return this; |
|
212 }, |
|
213 |
|
214 /** |
|
215 * Sets the window scroll and window resize triggers for any group that is fold-conditional (i.e., has a fold distance set). |
|
216 * @method _setFoldTriggers |
|
217 * @private |
|
218 */ |
|
219 _setFoldTriggers: function() { |
|
220 if (this._areFoldTriggersSet) { |
|
221 return; |
|
222 } |
|
223 |
|
224 |
|
225 var wrappedFoldCheck = function() { |
|
226 this._foldCheck(); |
|
227 }; |
|
228 this._triggers.push( Y.on('scroll', wrappedFoldCheck, window, this) ); |
|
229 this._triggers.push( Y.on('resize', wrappedFoldCheck, window, this) ); |
|
230 this._areFoldTriggersSet = true; |
|
231 }, |
|
232 |
|
233 /** |
|
234 * Performs necessary setup at domready time. |
|
235 * Initiates time limit for group; executes the fold check for the images. |
|
236 * @method _onloadTasks |
|
237 * @private |
|
238 */ |
|
239 _onloadTasks: function() { |
|
240 var timeLim = this.get('timeLimit'); |
|
241 if (timeLim && timeLim > 0) { |
|
242 this._timeout = setTimeout(this._getFetchTimeout(), timeLim * 1000); |
|
243 } |
|
244 |
|
245 if (! Y.Lang.isUndefined(this.get('foldDistance'))) { |
|
246 this._foldCheck(); |
|
247 } |
|
248 }, |
|
249 |
|
250 /** |
|
251 * Returns the group's <code>fetch</code> method, with the proper closure, for use with <code>setTimeout</code>. |
|
252 * @method _getFetchTimeout |
|
253 * @return {Function} group's <code>fetch</code> method |
|
254 * @private |
|
255 */ |
|
256 _getFetchTimeout: function() { |
|
257 var self = this; |
|
258 return function() { self.fetch(); }; |
|
259 }, |
|
260 |
|
261 /** |
|
262 * Registers an image with the group. |
|
263 * 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. |
|
264 * @method registerImage |
|
265 * @param {Object} * A configuration object literal with attribute name/value pairs (passed through to a <code>Y.ImgLoadImgObj</code> constructor) |
|
266 * @return {Object} <code>Y.ImgLoadImgObj</code> that was registered |
|
267 */ |
|
268 registerImage: function() { |
|
269 var domId = arguments[0].domId; |
|
270 if (! domId) { |
|
271 return null; |
|
272 } |
|
273 |
|
274 |
|
275 this._imgObjs[domId] = new Y.ImgLoadImgObj(arguments[0]); |
|
276 return this._imgObjs[domId]; |
|
277 }, |
|
278 |
|
279 /** |
|
280 * Displays the images in the group. |
|
281 * 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. |
|
282 * @method fetch |
|
283 */ |
|
284 fetch: function() { |
|
285 |
|
286 // done with the triggers |
|
287 this._clearTriggers(); |
|
288 |
|
289 // fetch whatever we need to by className |
|
290 this._fetchByClass(); |
|
291 |
|
292 // fetch registered images |
|
293 for (var id in this._imgObjs) { |
|
294 if (this._imgObjs.hasOwnProperty(id)) { |
|
295 this._imgObjs[id].fetch(); |
|
296 } |
|
297 } |
|
298 }, |
|
299 |
|
300 /** |
|
301 * Clears the timeout and all triggers associated with the group. |
|
302 * @method _clearTriggers |
|
303 * @private |
|
304 */ |
|
305 _clearTriggers: function() { |
|
306 clearTimeout(this._timeout); |
|
307 // detach all listeners |
|
308 for (var i=0, len = this._triggers.length; i < len; i++) { |
|
309 this._triggers[i].detach(); |
|
310 } |
|
311 }, |
|
312 |
|
313 /** |
|
314 * 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. |
|
315 * @method _foldCheck |
|
316 * @private |
|
317 */ |
|
318 _foldCheck: function() { |
|
319 |
|
320 var allFetched = true, |
|
321 viewReg = Y.DOM.viewportRegion(), |
|
322 hLimit = viewReg.bottom + this.get('foldDistance'), |
|
323 id, imgFetched, els, i, len; |
|
324 |
|
325 // unless we've uncovered new frontiers, there's no need to continue |
|
326 if (hLimit <= this._maxKnownHLimit) { |
|
327 return; |
|
328 } |
|
329 this._maxKnownHLimit = hLimit; |
|
330 |
|
331 for (id in this._imgObjs) { |
|
332 if (this._imgObjs.hasOwnProperty(id)) { |
|
333 imgFetched = this._imgObjs[id].fetch(hLimit); |
|
334 allFetched = allFetched && imgFetched; |
|
335 } |
|
336 } |
|
337 |
|
338 // and by class |
|
339 if (this._className) { |
|
340 if (this._classImageEls === null) { |
|
341 // get all the relevant elements and store them |
|
342 this._classImageEls = []; |
|
343 els = Y.all('.' + this._className); |
|
344 els.each( function(node) { this._classImageEls.push( { el: node, y: node.getY(), fetched: false } ); }, this); |
|
345 } |
|
346 els = this._classImageEls; |
|
347 for (i=0, len = els.length; i < len; i++) { |
|
348 if (els[i].fetched) { |
|
349 continue; |
|
350 } |
|
351 if (els[i].y && els[i].y <= hLimit) { |
|
352 //els[i].el.removeClass(this._className); |
|
353 this._updateNodeClassName(els[i].el); |
|
354 els[i].fetched = true; |
|
355 } |
|
356 else { |
|
357 allFetched = false; |
|
358 } |
|
359 } |
|
360 } |
|
361 |
|
362 // if allFetched, remove listeners |
|
363 if (allFetched) { |
|
364 this._clearTriggers(); |
|
365 } |
|
366 }, |
|
367 |
|
368 /** |
|
369 * Updates a given node, removing the ImageLoader class name. If the |
|
370 * node is an img and the classNameAction is "enhanced", then node |
|
371 * class name is removed and also the src attribute is set to the |
|
372 * image URL as well as clearing the style background image. |
|
373 * @method _updateNodeClassName |
|
374 * @param node {Node} The node to act on. |
|
375 * @private |
|
376 */ |
|
377 _updateNodeClassName: function(node){ |
|
378 var url; |
|
379 |
|
380 if (this.get("classNameAction") == "enhanced"){ |
|
381 |
|
382 if (node.get("tagName").toLowerCase() == "img"){ |
|
383 url = node.getStyle("backgroundImage"); |
|
384 /url\(["']?(.*?)["']?\)/.test(url); |
|
385 url = RegExp.$1; |
|
386 node.set("src", url); |
|
387 node.setStyle("backgroundImage", ""); |
|
388 } |
|
389 } |
|
390 |
|
391 node.removeClass(this._className); |
|
392 }, |
|
393 |
|
394 /** |
|
395 * 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. |
|
396 * @method _fetchByClass |
|
397 * @private |
|
398 */ |
|
399 _fetchByClass: function() { |
|
400 if (! this._className) { |
|
401 return; |
|
402 } |
|
403 |
|
404 |
|
405 Y.all('.' + this._className).each(Y.bind(this._updateNodeClassName, this)); |
|
406 } |
|
407 |
|
408 }; |
|
409 |
|
410 |
|
411 Y.extend(Y.ImgLoadGroup, Y.Base, groupProto); |
|
412 |
|
413 |
|
414 //------------------------------------------------ |
|
415 |
|
416 |
|
417 /** |
|
418 * Image objects to be registered with the groups |
|
419 * @class ImgLoadImgObj |
|
420 * @extends Base |
|
421 * @constructor |
|
422 */ |
|
423 Y.ImgLoadImgObj = function() { |
|
424 Y.ImgLoadImgObj.superclass.constructor.apply(this, arguments); |
|
425 this._init(); |
|
426 }; |
|
427 |
|
428 Y.ImgLoadImgObj.NAME = 'imgLoadImgObj'; |
|
429 |
|
430 Y.ImgLoadImgObj.ATTRS = { |
|
431 /** |
|
432 * HTML DOM id of the image element. |
|
433 * @attribute domId |
|
434 * @type String |
|
435 */ |
|
436 domId: { |
|
437 value: null, |
|
438 writeOnce: true |
|
439 }, |
|
440 |
|
441 /** |
|
442 * Background URL for the image. |
|
443 * For an image whose URL is specified by "<code>background-image</code>" in the element's style. |
|
444 * @attribute bgUrl |
|
445 * @type String |
|
446 */ |
|
447 bgUrl: { |
|
448 value: null |
|
449 }, |
|
450 |
|
451 /** |
|
452 * Source URL for the image. |
|
453 * For an image whose URL is specified by a "<code>src</code>" attribute in the DOM element. |
|
454 * @attribute srcUrl |
|
455 * @type String |
|
456 */ |
|
457 srcUrl: { |
|
458 value: null |
|
459 }, |
|
460 |
|
461 /** |
|
462 * Pixel width of the image. Will be set as a <code>width</code> attribute on the DOM element after the image is fetched. |
|
463 * Defaults to the natural width of the image (no <code>width</code> attribute will be set). |
|
464 * Usually only used with src images. |
|
465 * @attribute width |
|
466 * @type Int |
|
467 */ |
|
468 width: { |
|
469 value: null |
|
470 }, |
|
471 |
|
472 /** |
|
473 * Pixel height of the image. Will be set as a <code>height</code> attribute on the DOM element after the image is fetched. |
|
474 * Defaults to the natural height of the image (no <code>height</code> attribute will be set). |
|
475 * Usually only used with src images. |
|
476 * @attribute height |
|
477 * @type Int |
|
478 */ |
|
479 height: { |
|
480 value: null |
|
481 }, |
|
482 |
|
483 /** |
|
484 * Whether the image's <code>style.visibility</code> should be set to <code>visible</code> after the image is fetched. |
|
485 * Used when setting images as <code>visibility:hidden</code> prior to image fetching. |
|
486 * @attribute setVisible |
|
487 * @type Boolean |
|
488 */ |
|
489 setVisible: { |
|
490 value: false |
|
491 }, |
|
492 |
|
493 /** |
|
494 * Whether the image is a PNG. |
|
495 * PNG images get special treatment in that the URL is specified through AlphaImageLoader for IE, versions 6 and earlier. |
|
496 * Only used with background images. |
|
497 * @attribute isPng |
|
498 * @type Boolean |
|
499 */ |
|
500 isPng: { |
|
501 value: false |
|
502 }, |
|
503 |
|
504 /** |
|
505 * AlphaImageLoader <code>sizingMethod</code> property to be set for the image. |
|
506 * Only set if <code>isPng</code> value for this image is set to <code>true</code>. |
|
507 * Defaults to <code>scale</code>. |
|
508 * @attribute sizingMethod |
|
509 * @type String |
|
510 */ |
|
511 sizingMethod: { |
|
512 value: 'scale' |
|
513 }, |
|
514 |
|
515 /** |
|
516 * AlphaImageLoader <code>enabled</code> property to be set for the image. |
|
517 * Only set if <code>isPng</code> value for this image is set to <code>true</code>. |
|
518 * Defaults to <code>true</code>. |
|
519 * @attribute enabled |
|
520 * @type String |
|
521 */ |
|
522 enabled: { |
|
523 value: 'true' |
|
524 } |
|
525 |
|
526 }; |
|
527 |
|
528 var imgProto = { |
|
529 |
|
530 /** |
|
531 * Initialize all private members needed for the group. |
|
532 * @method _init |
|
533 * @private |
|
534 */ |
|
535 _init: function() { |
|
536 |
|
537 /** |
|
538 * Whether this image has already been fetched. |
|
539 * In the case of fold-conditional groups, images won't be fetched twice. |
|
540 * @property _fetched |
|
541 * @private |
|
542 * @type Boolean |
|
543 */ |
|
544 this._fetched = false; |
|
545 |
|
546 /** |
|
547 * The Node object returned from <code>Y.one</code>, to avoid repeat calls to access the DOM. |
|
548 * @property _imgEl |
|
549 * @private |
|
550 * @type Object |
|
551 */ |
|
552 this._imgEl = null; |
|
553 |
|
554 /** |
|
555 * The vertical position returned from <code>getY</code>, to avoid repeat calls to access the DOM. |
|
556 * The Y position is checked only for images registered with fold-conditional groups. The position is checked first at page load (domready) |
|
557 * and this caching enhancement assumes that the image's vertical position won't change after that first check. |
|
558 * @property _yPos |
|
559 * @private |
|
560 * @type Int |
|
561 */ |
|
562 this._yPos = null; |
|
563 }, |
|
564 |
|
565 /** |
|
566 * Displays the image; puts the URL into the DOM. |
|
567 * This method shouldn't be called externally, but is not private in the rare event that it needs to be called immediately. |
|
568 * @method fetch |
|
569 * @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 |
|
570 * @return {Boolean} Whether the image has been fetched (either during this execution or previously) |
|
571 */ |
|
572 fetch: function(withinY) { |
|
573 if (this._fetched) { |
|
574 return true; |
|
575 } |
|
576 |
|
577 var el = this._getImgEl(), |
|
578 yPos; |
|
579 if (! el) { |
|
580 return false; |
|
581 } |
|
582 |
|
583 if (withinY) { |
|
584 // need a distance check |
|
585 yPos = this._getYPos(); |
|
586 if (! yPos || yPos > withinY) { |
|
587 return false; |
|
588 } |
|
589 } |
|
590 |
|
591 |
|
592 // apply url |
|
593 if (this.get('bgUrl') !== null) { |
|
594 // bg url |
|
595 if (this.get('isPng') && Y.UA.ie && Y.UA.ie <= 6) { |
|
596 // png for which to apply AlphaImageLoader |
|
597 el.setStyle('filter', 'progid:DXImageTransform.Microsoft.AlphaImageLoader(src="' + this.get('bgUrl') + '", sizingMethod="' + this.get('sizingMethod') + '", enabled="' + this.get('enabled') + '")'); |
|
598 } |
|
599 else { |
|
600 // regular bg image |
|
601 el.setStyle('backgroundImage', "url('" + this.get('bgUrl') + "')"); |
|
602 } |
|
603 } |
|
604 else if (this.get('srcUrl') !== null) { |
|
605 // regular src image |
|
606 el.setAttribute('src', this.get('srcUrl')); |
|
607 } |
|
608 |
|
609 // apply attributes |
|
610 if (this.get('setVisible')) { |
|
611 el.setStyle('visibility', 'visible'); |
|
612 } |
|
613 if (this.get('width')) { |
|
614 el.setAttribute('width', this.get('width')); |
|
615 } |
|
616 if (this.get('height')) { |
|
617 el.setAttribute('height', this.get('height')); |
|
618 } |
|
619 |
|
620 this._fetched = true; |
|
621 |
|
622 return true; |
|
623 }, |
|
624 |
|
625 /** |
|
626 * Gets the object (as a <code>Y.Node</code>) of the DOM element indicated by "<code>domId</code>". |
|
627 * @method _getImgEl |
|
628 * @return {Object} DOM element of the image as a <code>Y.Node</code> object |
|
629 * @private |
|
630 */ |
|
631 _getImgEl: function() { |
|
632 if (this._imgEl === null) { |
|
633 this._imgEl = Y.one('#' + this.get('domId')); |
|
634 } |
|
635 return this._imgEl; |
|
636 }, |
|
637 |
|
638 /** |
|
639 * Gets the Y position of the node in page coordinates. |
|
640 * Expects that the page-coordinate position of the image won't change. |
|
641 * @method _getYPos |
|
642 * @return {Object} The Y position of the image |
|
643 * @private |
|
644 */ |
|
645 _getYPos: function() { |
|
646 if (this._yPos === null) { |
|
647 this._yPos = this._getImgEl().getY(); |
|
648 } |
|
649 return this._yPos; |
|
650 } |
|
651 |
|
652 }; |
|
653 |
|
654 |
|
655 Y.extend(Y.ImgLoadImgObj, Y.Base, imgProto); |
|
656 |
|
657 |
|
658 |
|
659 |
|
660 }, '3.10.3', {"requires": ["base-base", "node-style", "node-screen"]}); |