← Back to branch summary

~ubuntu-branches/ubuntu/raring/maas/raring-updates

« back to all changes in this revision

Viewing changes to src/maasserver/static/jslibs/yui/3.4.1/docs/imageloader/index.html

  • Committer: Package Import Robot
  • Author(s): Andres Rodriguez
  • Date: 2012-07-03 17:42:37 UTC
  • mfrom: (1.1.13)
  • Revision ID: package-import@ubuntu.com-20120703174237-p8l0keuuznfg721k
Tags: 0.1+bzr709+dfsg-0ubuntu1
* New Upstream release
* debian/control:
  - Depends on python-celery, python-tempita, libjs-yui3-{full,min},
    libjs-raphael
* debian/maas.install:
  - Install apiclient, celeryconfig.py, maas-import-pxe-files, preseeds_v2.
  - Update to install various files from chroot, rather tha manually copy
    them from the source.
* debian/maas.links: symlink celeryconfig.py
* debian/maas.maas-celery.upstart: Add job.
* debian/rules:
  - Install celery upstart job.
  - Do not install jslibs as packages are now used.
  - Drop copying of maas_local_settings_sample.py as source now ships
    a maas_local_settings.py
* debian/patches:
  - 04-maas-http-fix.patch: Drop. Merged upstream.
  - 01-fix-database-settings.patch: Refreshed.
  - 99_enums_js.patch: Added until creation of enum.js / build process
    is fixed.
* debian/maas.postinst: Update bzr version to correctly handle upgrades.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/maasserver/static/jslibs/yui/3.4.1/docs/imageloader/index.html
1
 
<!DOCTYPE html>
2
 
<html lang="en">
3
 
<head>
4
 
    <meta charset="utf-8">
5
 
    <title>ImageLoader</title>
6
 
    <link rel="stylesheet" href="http://yui.yahooapis.com/3.4.0pr3/build/cssgrids/grids-min.css">
7
 
    <link rel="stylesheet" href="../assets/css/main.css">
8
 
    <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
9
 
    <script src="../../build/yui/yui-min.js"></script>
10
 
</head>
11
 
<body>
12
 
 
13
 
<div id="doc">
14
 
    <h1>ImageLoader</h1>
15
 
 
16
 
    
17
 
        <a href="#toc" class="jump">Jump to Table of Contents</a>
18
 
    
19
 
 
20
 
    <div class="yui3-g">
21
 
        <div id="main" class="yui3-u">
22
 
            <div class="content"><div class="intro">
23
 
  <p>
24
 
    The ImageLoader Utility allows you as an implementer to delay the loading of images on your web page until 
25
 
    such a time as your user is likely to see them. This can improve your overall pageload performance by deferring 
26
 
    the loading of some images that are not immediately visible at the time the page first renders. 
27
 
    Because images are often the heaviest components of a given page, deferring the loading of some images can 
28
 
    yield a marked improvement in the way the page "feels" to your user.
29
 
  </p>
30
 
 
31
 
  <p>
32
 
    The ImageLoader Utility lets you determine triggers and time limits to initiate image loading. 
33
 
    This allows you to ensure that the images are loaded before your user is likely to see them. 
34
 
    This technique, obviously, is appropriate only for images that are not immediately visible to your user at initial page load.
35
 
  </p>
36
 
</div>
37
 
 
38
 
<h2 id="getting-started">Getting Started</h2>
39
 
 
40
 
<p>
41
 
To include the source files for ImageLoader and its dependencies, first load
42
 
the YUI seed file if you haven't already loaded it.
43
 
</p>
44
 
 
45
 
<pre class="code prettyprint">&lt;script src=&quot;http:&#x2F;&#x2F;yui.yahooapis.com&#x2F;3.4.1&#x2F;build&#x2F;yui&#x2F;yui-min.js&quot;&gt;&lt;&#x2F;script&gt;</pre>
46
 
 
47
 
 
48
 
<p>
49
 
Next, create a new YUI instance for your application and populate it with the
50
 
modules you need by specifying them as arguments to the <code>YUI().use()</code> method.
51
 
YUI will automatically load any dependencies required by the modules you
52
 
specify.
53
 
</p>
54
 
 
55
 
<pre class="code prettyprint">&#x2F;&#x2F; Create a new YUI instance and populate it with the required modules.
56
 
YUI().use(&#x27;imageloader&#x27;, function (Y) {
57
 
    &#x2F;&#x2F; ImageLoader is available and ready for use. Add implementation
58
 
    &#x2F;&#x2F; code here.
59
 
});</pre>
60
 
 
61
 
 
62
 
<p>
63
 
For more information on creating YUI instances and on the
64
 
<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the
65
 
documentation for the <a href="../yui/index.html">YUI Global object</a>.
66
 
</p>
67
 
 
68
 
 
69
 
<h3 id="creating-an-image-group">Creating an Image Group</h3>
70
 
<p>
71
 
  Images are organized into groups. Each group has one or more triggers. A trigger is simply any DOM event, 
72
 
  such as the <code>mouseover</code> of a specific <code>&lt;div&gt;</code>, a button click, or a window scroll. 
73
 
  The images in a group won't load into the page until this trigger fires. Groups also have an optional time limit; 
74
 
  if none of the group's triggers are activated before the time limit expires, the images are fetched anyway.
75
 
</p>
76
 
<p>
77
 
  A group is defined as an instance of <code>Y.ImgLoadGroup</code>.  It comprises a collection of images that will 
78
 
  show up on the page based on the same triggers and time limit.
79
 
 
80
 
<pre class="code prettyprint">var myFirstGroup = new Y.ImgLoadGroup({ timeLimit: 2 });
81
 
myFirstGroup.addTrigger(&#x27;#someDivId&#x27;, &#x27;mouseover&#x27;);</pre>
82
 
 
83
 
</p>
84
 
<p>
85
 
  This defines a group triggered by a <code>mouseover</code> of the <code>&lt;div&gt;</code> with the HTML ID 
86
 
  of <code>someDivId</code>; with the <code>timeLimit</code> attribute we are specifying that all images 
87
 
  in <code>myFirstGroup</code> should load two seconds after the window's <code>load</code> event fires even 
88
 
  if our trigger hasn't been tripped.
89
 
</p>
90
 
  
91
 
<h3 id="adding-images-to-the-group">Adding Images to the Group</h3>
92
 
<p>
93
 
  Register one or more images with the group using the HTML ID of the image element and the URL for the image:
94
 
 
95
 
<pre class="code prettyprint">myFirstGroup.registerImage({
96
 
    domId: &#x27;idOfDivWaitingForImage&#x27;,
97
 
    bgUrl: &#x27;http:&#x2F;&#x2F;www.example.com&#x2F;image&#x2F;url&#x27;
98
 
});</pre>
99
 
 
100
 
</p>
101
 
<p>
102
 
  This will set the image at <code>http://www.example.com/image/url</code> as the background image of 
103
 
  the <code>&lt;div&gt;</code> with the ID <code>idOfDivWaitingForImage</code>.  There are three kinds of images you 
104
 
  can register with an ImageLoader group instance; see <a href="#addimages">Adding Images</a> below for more details on this process.
105
 
</p>
106
 
 
107
 
 
108
 
<h2 id="using">Using the ImageLoader Utility</h2>
109
 
<p>
110
 
  This section describes how to use the ImageLoader Utility in further detail.  It contains these subsections:
111
 
</p>
112
 
<ul>
113
 
  <li><a href="#performance">Performance Considerations</a></li>
114
 
  <li><a href="#approach">Approach</a></li>
115
 
  <li><a href="#triggers">Triggers</a></li>
116
 
  <li><a href="#customtriggers">Custom Event Triggers</a></li>
117
 
  <li><a href="#addimages">Adding Images</a></li>
118
 
  <li><a href="#fold">Loading Images Below the Fold</a></li>
119
 
  <li><a href="#visibility">Image Visibility</a></li>
120
 
  <li><a href="#classnames">Using Class Names</a></li>
121
 
</ul>
122
 
 
123
 
 
124
 
<h3 id="performance">Performance Considerations</h3>
125
 
<p>
126
 
  The images on your page require possible DNS lookups, new HTTP transactions, and ultimately the transmission 
127
 
  of image data in packets over the wire.  While all this is happening, the user is often left waiting for the 
128
 
  page to become fully functional. All of your <code>onload</code> JavaScript, for example, is deferred until 
129
 
  after all the page's images have finished loading.
130
 
</p>
131
 
<p>
132
 
  Should the user have to wait for all of these images? If the images are front and center on the page, then yes, 
133
 
  suffering the load time is necessary. But what about images that the user doesn't see right away &mdash; the images 
134
 
  below the fold; the images hidden towards the end of a carousel; the images that won't appear until a non-default 
135
 
  tab of some module is clicked? ImageLoader allows you to delay the load of these images until after page load so 
136
 
  that the page is fully functional more quickly. And, by using triggers, you can ensure that the images are loaded 
137
 
  just before the user needs them so that there's no degradation of user experience.
138
 
</p>
139
 
 
140
 
<h3 id="approach">Approach</h3>
141
 
<p>
142
 
  How can you anticipate when the user will be able to see images? Well, you as a developer know your page, 
143
 
  and you know what actions are available to the user. You can utilize your knowledge to identify user events 
144
 
  that indicate what the user is about to see.
145
 
</p>
146
 
<p>
147
 
  For example, you know that any image lying below the fold won't be visible until the user either scrolls 
148
 
  the page or resizes the browser window. In a tabbed module, you know that the user can't click one of the 
149
 
  tabs until she mouses over that tab.
150
 
</p>
151
 
<p>
152
 
  Consequently, you can use scroll events, mouseover events, or other indicators of user intent to stay one 
153
 
  step ahead of the user and decide when to load images. The ImageLoader Utility lets you do exactly this.
154
 
</p>
155
 
 
156
 
<h3 id="triggers">Triggers</h3>
157
 
<p>
158
 
  Images are grouped together in terms of which user action(s) should trigger their loading. 
159
 
  A trigger is simply any DOM event. Your first step is to create an ImageLoader group object and define its trigger:
160
 
 
161
 
<pre class="code prettyprint">var myFirstGroup = new Y.ImgLoadGroup({
162
 
    timeLimit: 2 
163
 
});
164
 
myFirstGroup.addTrigger(&#x27;#someDivId&#x27;, &#x27;mouseover&#x27;);</pre>
165
 
 
166
 
</p>
167
 
<p>
168
 
  The <code>timeLimit</code> attribute is a time limit for the group. 
169
 
  If the user has not performed the trigger event within the specified time limit, the images are fetched anyway. 
170
 
  You can elect to not specify either the time limit or the trigger (indicating the user must perform the trigger event, 
171
 
  or there should only be a simple time delay, respectively.)
172
 
</p>
173
 
<p>
174
 
  You can have as many triggers as you wish for a group. 
175
 
  Just add them with the <code>group</code> class's <code>addTrigger</code> method:
176
 
 
177
 
<pre class="code prettyprint">myFirstGroup.addTrigger(&#x27;#someOtherDivId&#x27;, &#x27;click&#x27;);</pre>
178
 
 
179
 
</p>
180
 
<p>
181
 
  The trigger conditionals are disjunctive; the first one to fire initiates the image fetching.
182
 
</p>
183
 
 
184
 
<h3 id="customtriggers">Custom Event Triggers</h3>
185
 
<p>
186
 
  You can also specify custom events as triggers. If the event belongs to the <code>Y</code> instance, 
187
 
  call <code>addCustomTrigger</code> with the event name:
188
 
 
189
 
<pre class="code prettyprint">myFirstGroup.addCustomTrigger(&#x27;mycustomevent:imgloadevent&#x27;);</pre>
190
 
 
191
 
</p>
192
 
<p>
193
 
  Alternatively, if you have a custom event attached to a local object, you can specify this in the 
194
 
  <code>addCustomTrigger</code> call:
195
 
 
196
 
<pre class="code prettyprint">myFirstGroup.addCustomTrigger(&#x27;mycustomevent:imgloadevent2&#x27;, myCustomEvent);</pre>
197
 
 
198
 
</p>
199
 
<p>
200
 
  And this group's images will be fetched upon <code>myCustomEvent.fire('mycustomevent:imgloadevent2');</code>.
201
 
</p>
202
 
 
203
 
<h3 id="addimages">Adding Images</h3>
204
 
<p>Once a group is created, you can add as many images as you'd like to it. There are three types of images:</p>
205
 
<ol>
206
 
        <li>
207
 
          <strong>background image</strong> (a <code>&lt;div&gt;</code> with a background image; URL set in <code>style.backgroundImage</code>).  
208
 
          Use the <code>bgUrl</code> attribute to register this kind of image.
209
 
        </li>
210
 
        <li>
211
 
          <strong>source image</strong> (an <code>&lt;img&gt;</code> tag; URL set in a <code>url</code> attribute).  
212
 
          Use the <code>srcUrl</code> attribute to register this kind of image.
213
 
        </li>
214
 
        <li>
215
 
          <strong>png background image</strong> (a <code>&lt;div&gt;</code> with a png background image; for IE6, 
216
 
          sets an alpha filter <code>src</code>; for other browsers sets a background image).  
217
 
          Use the <code>isPng</code> and <code>bgUrl</code> attributes to register this kind of image.
218
 
        </li>
219
 
</ol>
220
 
<p>
221
 
  To add an image to a group, register the DOM ID of the image element and the image URL with the 
222
 
  <code>registerImage</code> method:
223
 
 
224
 
<pre class="code prettyprint">myFirstGroup.registerImage({
225
 
    domId: &#x27;idOfDivWaitingForImage&#x27;, 
226
 
    bgUrl: &#x27;http:&#x2F;&#x2F;www.example.com&#x2F;image&#x2F;url&#x27;
227
 
});
228
 
myFirstGroup.registerImage({ 
229
 
    domId: &#x27;idOfImgWaitingForImage&#x27;, 
230
 
    srcUrl: &#x27;http:&#x2F;&#x2F;www.example.com&#x2F;other&#x2F;image&#x2F;url&#x27; 
231
 
});
232
 
myFirstGroup.registerImage({ 
233
 
    domId: &#x27;idOfDivWaitingForPngImage&#x27;, 
234
 
    bgUrl: &#x27;http:&#x2F;&#x2F;www.example.com&#x2F;png&#x2F;image&#x2F;url&#x27;,
235
 
    isPng: true
236
 
});</pre>
237
 
 
238
 
</p>
239
 
<p>
240
 
  This will set the image at <code>http://www.example.com/image/url</code> as the background-image of 
241
 
  the <code>&lt;div&gt;</code> with the ID <code>idOfDivWaitingForImage</code> and likewise with the two other image elements.
242
 
</p>
243
 
 
244
 
<h3 id="fold">Loading Images Below the Fold</h3>
245
 
<p>
246
 
  A group can check its images at the DOM ready state and immediately begin loading those that are above the fold 
247
 
  (i.e., inside the current viewport) while delaying the load of those that aren't. Just set a value for 
248
 
  the <code>foldDistance</code> property of the group. Images are checked and loaded in a cascading fashion. 
249
 
  That is, each image will be loaded only when it comes within <code>foldDistance</code> pixels of the bottom of the viewport. 
250
 
  The effect is that images are loaded as needed as the user scrolls down the page. When you set a <code>foldDistance</code>, 
251
 
  the group automatically gets window <code>scroll</code> and window <code>resize</code> triggers.
252
 
<pre class="code prettyprint">var foldGroup = new Y.ImgLoadGroup({
253
 
    foldDistance: 30
254
 
});
255
 
foldGroup.registerImage({
256
 
    domId: &#x27;partwayDownPageImage&#x27;, 
257
 
    bgUrl: &#x27;http:&#x2F;&#x2F;www.example.com&#x2F;image&#x2F;url&#x27;
258
 
});</pre>
259
 
 
260
 
</p>
261
 
 
262
 
<h3 id="visibility">Image Visibility</h3>
263
 
<p>
264
 
  You can set your <code>&lt;img&gt;</code> tags to have the CSS property <code>visibility:hidden</code>. 
265
 
  This will allow your page to keep its structure until the image is actually loaded. Since these images are probably 
266
 
  out of the viewport anyway, this may not make a perceptible difference, but it will help some browsers avoid reflowing 
267
 
  the page when deferred images are loaded. To accomplish this using ImageLoader, set the <code>setVisible</code> 
268
 
  attribute of the image to <code>true</code> when you register the image; ImageLoader will then set the <code>visibility</code> 
269
 
  property to <code>visible</code> when the image is fetched.
270
 
</p>
271
 
 
272
 
<h3 id="classnames">Using Class Names</h3>
273
 
<p>
274
 
  As an alternative to registering each image with a group, you can use CSS class names to group images together. 
275
 
  When using this approach, images that are part of the same group should all share a common class name. 
276
 
  Each should also have its image set as the element's background image via CSS in the element's <code>style</code> attribute. 
277
 
  To prevent the image from loading immediately when the element renders, create a CSS style definition for that 
278
 
  class overriding the background image to <code>none</code>. Lastly, set the <code>className</code> attribute of the 
279
 
  ImageLoader group.
280
 
</p>
281
 
<p>
282
 
  The following combination of CSS, HTML, and JavaScript illustrates this approach:
283
 
<pre class="code prettyprint">&lt;div 
284
 
  class=&#x27;yui-imgload-somegroup&#x27; 
285
 
  style=&#x27;background-image:url(&quot;http:&#x2F;&#x2F;www.example.com&#x2F;image&#x2F;url&quot;);&#x27;&gt;
286
 
&lt;&#x2F;div&gt;
287
 
 
288
 
&lt;style&gt;
289
 
  .yui-imgload-somegroup { 
290
 
    background:none !important; 
291
 
  }
292
 
&lt;&#x2F;style&gt;
293
 
 
294
 
&lt;script&gt;
295
 
  someGroup.set(&#x27;className&#x27;, &#x27;yui-imgload-somegroup&#x27;);
296
 
&lt;&#x2F;script&gt;</pre>
297
 
 
298
 
</p>
299
 
 
300
 
 
301
 
<h2 id="caveats">Important Usage Requirements</h2>
302
 
 
303
 
<p>
304
 
  There are some important things to keep in mind while using the ImageLoader Utility. 
305
 
  Otherwise it may not work the way you expect, or it may have some undesired side effects.
306
 
</p>
307
 
 
308
 
<h3 id="src-attribute-of-source-images">"src" Attribute of Source Images</h3>
309
 
<p>
310
 
  When using ImageLoader with <code>&lt;img&gt;</code> elements (via the <code>srcUrl</code> attribute), 
311
 
  leave the <code>src</code> attribute out of the HTML element altogether. Do not set an empty string for 
312
 
  the value of <code>src</code>. Some browsers react to this by assuming the empty string means "/", and 
313
 
  consequently the browser re-requests the current HTML page and tries to stuff it into the <code>&lt;img&gt;</code> element. 
314
 
  This is bad news for performance.
315
 
</p>
316
 
<p>
317
 
  <code>
318
 
    &lt;img id="anImgEl" /&gt;
319
 
    <br />
320
 
    <strike>&lt;img id="anImgEl" src="" /&gt;</strike>
321
 
  </code>
322
 
</p>
323
 
 
324
 
<h3 id="resizing-images">Resizing Images</h3>
325
 
<p>
326
 
  When resizing <code>&lt;img&gt;</code> elements (via <code>height</code> and <code>width</code> attributes) on the fly, 
327
 
  the height and width of the image must be specified in the JavaScript. Do this by setting <code>width</code>/<code>height</code> 
328
 
  attributes in the <code>registerImage</code> call. Failure to do this will result in no resizing. Browsers ignore width/height 
329
 
  set in the HTML when there is no <code>src</code> attribute. And when the <code>src</code> is finally set, the width/height end 
330
 
  up being the image's natural size.
331
 
</p>
332
 
<p>
333
 
  <code>
334
 
    someGroup.registerImage({ domId: "someImgDiv", srcUrl: "http://www.example.com/image/url", width: W, height: H });
335
 
    <br />
336
 
    <strike>someGroup.registerImage({ domId: "someImgDiv", srcUrl: "http://www.example.com/image/url" });</strike>
337
 
  </code>
338
 
</p>
339
 
</div>
340
 
        </div>
341
 
 
342
 
        <div id="sidebar" class="yui3-u">
343
 
            
344
 
                <div id="toc" class="sidebox">
345
 
                    <div class="hd">
346
 
                        <h2 class="no-toc">Table of Contents</h2>
347
 
                    </div>
348
 
 
349
 
                    <div class="bd">
350
 
                        <ul class="toc">
351
 
<li>
352
 
<a href="#getting-started">Getting Started</a>
353
 
<ul class="toc">
354
 
<li>
355
 
<a href="#creating-an-image-group">Creating an Image Group</a>
356
 
</li>
357
 
<li>
358
 
<a href="#adding-images-to-the-group">Adding Images to the Group</a>
359
 
</li>
360
 
</ul>
361
 
</li>
362
 
<li>
363
 
<a href="#using">Using the ImageLoader Utility</a>
364
 
<ul class="toc">
365
 
<li>
366
 
<a href="#performance">Performance Considerations</a>
367
 
</li>
368
 
<li>
369
 
<a href="#approach">Approach</a>
370
 
</li>
371
 
<li>
372
 
<a href="#triggers">Triggers</a>
373
 
</li>
374
 
<li>
375
 
<a href="#customtriggers">Custom Event Triggers</a>
376
 
</li>
377
 
<li>
378
 
<a href="#addimages">Adding Images</a>
379
 
</li>
380
 
<li>
381
 
<a href="#fold">Loading Images Below the Fold</a>
382
 
</li>
383
 
<li>
384
 
<a href="#visibility">Image Visibility</a>
385
 
</li>
386
 
<li>
387
 
<a href="#classnames">Using Class Names</a>
388
 
</li>
389
 
</ul>
390
 
</li>
391
 
<li>
392
 
<a href="#caveats">Important Usage Requirements</a>
393
 
<ul class="toc">
394
 
<li>
395
 
<a href="#src-attribute-of-source-images">"src" Attribute of Source Images</a>
396
 
</li>
397
 
<li>
398
 
<a href="#resizing-images">Resizing Images</a>
399
 
</li>
400
 
</ul>
401
 
</li>
402
 
</ul>
403
 
                    </div>
404
 
                </div>
405
 
            
406
 
 
407
 
            
408
 
                <div class="sidebox">
409
 
                    <div class="hd">
410
 
                        <h2 class="no-toc">Examples</h2>
411
 
                    </div>
412
 
 
413
 
                    <div class="bd">
414
 
                        <ul class="examples">
415
 
                            
416
 
                                
417
 
                                    <li data-description="Demonstrates the basic features and operation of the ImageLoader Utility, deferring the loading of images until specific events happen or specific time limits expire.">
418
 
                                        <a href="basic-features.html">Basic Features of the ImageLoader Utility</a>
419
 
                                    </li>
420
 
                                
421
 
                            
422
 
                                
423
 
                                    <li data-description="Loading images above the fold immediately while deferring the loading of images below the fold.">
424
 
                                        <a href="below-fold.html">Loading Images Below the Fold</a>
425
 
                                    </li>
426
 
                                
427
 
                            
428
 
                                
429
 
                                    <li data-description="Using CSS class names to target specific images for deferred loading.">
430
 
                                        <a href="imageloader-class-names.html">Using ImageLoader with CSS Class Names</a>
431
 
                                    </li>
432
 
                                
433
 
                            
434
 
                        </ul>
435
 
                    </div>
436
 
                </div>
437
 
            
438
 
 
439
 
            
440
 
        </div>
441
 
    </div>
442
 
</div>
443
 
 
444
 
<script src="../assets/vendor/prettify/prettify-min.js"></script>
445
 
<script>prettyPrint();</script>
446
 
 
447
 
</body>
448
 
</html>