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