This repository has been archived by the owner on Feb 22, 2023. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathblazy-documentation.html
291 lines (290 loc) · 20.2 KB
/
blazy-documentation.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
<div class="entry-content">
<blockquote>
<h3><span style="color: #ff6600;">2015.11.14: </span><span style="color: #ff6600;">New release, bLazy version 1.5.1</span></h3>
</blockquote>
<p><span style="line-height: 1.5;">bLazy is a lightweight script for lazy loading and multi-serving images. </span><span style="line-height: 1.5;">It’s written in pure JavaScript why it doesn’t depend on 3rd-party libraries </span><span style="line-height: 1.5;">such as jQuery. bLazy works on all modern browsers, including on IE7+.</span></p>
<div style="background-color: #1e1e1e; text-align: center; border-radius: 10px; padding: 10px; color: #fff;">
<h1><a style="color: #fff;" href="http://dinbror.dk/blazy">Demo </a>| <a style="color: #fff;" href="https://raw.github.com/dinbror/blazy/master/blazy.min.js">Download</a></h1>
<div style="display: inline-block; padding: 7px 0 0;"><iframe src="http://ghbtns.com/github-btn.html?user=dinbror&repo=blazy&type=watch&count=true" width="80" height="20" frameborder="0" scrolling="0"></iframe><iframe src="http://ghbtns.com/github-btn.html?user=dinbror&repo=blazy&type=fork&count=true" width="95" height="20" frameborder="0" scrolling="0"></iframe></div>
</div>
<h3><strong>Contents</strong></h3>
<ol>
<li><a href="#Usage">How to use bLazy</a></li>
<li><a href="#Options">Options</a>
<ul>
<li><a href="#Selector">Selector</a></li>
<li><a href="#Offset">Offset</a></li>
<li><a href="#Inside">Container</a></li>
<li><a href="#Callback">Callbacks, succes & error</a></li>
<li><a href="#Retina">Retina images</a></li>
<li><a href="#Background">Background images</a></li>
<li><a href="#Multi">Multi-serve images</a></li>
<li><a href="#Transitions">Image transitions</a></li>
</ul>
</li>
<li><a href="#Functions">Public functions</a></li>
<li><a href="#Responsive">Responsive Images</a></li>
<li><a href="#iframe">Iframes, unity games etc.</a></li>
<li><a href="#angular">With AngularJS</a></li>
<li><a href="https://github.com/dinbror/blazy#changelog" target="_blank">Changelog (github)</a></li>
<li><a href="#license">License</a></li>
<li><a href="#Support">Support</a></li>
</ol>
<h3 id="Usage">How to use bLazy (lazy load images)</h3>
<p>You can lazy load your images in just two easy steps.</p>
<p><strong>Step 1) </strong>Change your image markup a bit.</p>
<ul>
<li>Add class “b-lazy”.</li>
<li>Add a placeholder image to the image source (src). In my example I’m using a <a href="http://probablyprogramming.com/2009/03/15/the-tiniest-gif-ever" target="_blank">base64 encoded transparent gif</a> so it won’t do any extra requests.</li>
<li>Save the real image source in the data-src attribute</li>
</ul>
<pre> <img class=<span class="code-string">"b-lazy"</span>
src=<span class="code-string">data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==</span>
data-src=<span class="code-string">"image.jpg"</span>
alt=<span class="code-string">"alt-text"</span>
/></pre>
<p><strong>Step 2) </strong>Include blazy.js and initialize it. If you’re using jQuery (or simliar) do it in document.ready:</p>
<pre> <script src="<span class="code-string">blazy.js</span>"></script>
<script>
;(<span class="code-function">function</span>() {
<span class="code-comment">// Initialize</span>
var bLazy = new <span class="code-function">Blazy</span>();
})();
</script></pre>
<h3 id="Options">bLazy comes with a few options</h3>
<table style="border: 0px none;" border="0" width="100%">
<tbody>
<tr>
<td style="background-color: #1e1e1e;" colspan="2"><span style="color: #ffffff;"><strong>Options- key [<em>type</em>] (default value)</strong></span></td>
</tr>
<tr>
<td width="30%"><strong>breakpoints</strong>[<em>array</em>] (false)</td>
<td>Multi-serve images based on screen size. <a href="#Multi">Go to multi-serve image example</a></td>
</tr>
<tr>
<td width="30%"><b>container </b>[<em>string</em>](window)</td>
<td>If you want to lazy load elements inside a scrolling container change the default value to the selector of the container</td>
</tr>
<tr>
<td width="30%"><strong>error </strong>[<em>function(ele, msg)</em>] (false)</td>
<td>Callback for when something goes wrong. There are two error messages, <em>missing</em> and <em>invalid</em>. You’ll get missing if no data-src is defined. Invalid if the data-src is invalid. <a href="#Callback">Go to callback example</a></td>
</tr>
<tr>
<td width="30%"><b>errorClass </b>[<em>string</em>](‘b-error’)</td>
<td>The classname an element will get if something goes wrong.</td>
</tr>
<tr>
<td width="30%"><b>loadInvisible </b>[<em>bool</em>](false)</td>
<td>Set to true if you want to load invisible (hidden) elements.</td>
</tr>
<tr>
<td width="30%"><strong>offset </strong>[<em>int</em>] (100)</td>
<td>The offset controls how early you want the elements to be loaded before they’re visible. Default is 100, so 100px before an element is visible it’ll start loading.</td>
</tr>
<tr>
<td width="30%"><strong>saveViewportOffsetDelay </strong><em>[int</em>] (50)</td>
<td>Delay for how often it should call the saveViewportOffset function on resize. Default is 50ms.</td>
</tr>
<tr>
<td width="30%"><strong>selector</strong>[<em>string</em>] (‘.b-lazy’)</td>
<td>Element selector for elements that should lazy load. If you want to lazy load all images write ‘img’. You can add multiple selectors separated with comma; ‘.b-lazy, .bLazy, .blazy’.</td>
</tr>
<tr>
<td width="30%"><strong>separator </strong>[<em>char</em>](‘|’)</td>
<td>Used if you want to pass retina images: data-src=”image.jpg|[email protected]”. <a href="#Retina">Go to the retina image example</a></td>
</tr>
<tr>
<td width="30%"><strong>src</strong> [<em>string</em>] (‘data-src’)</td>
<td>Attribute where the original element source can be found</td>
</tr>
<tr>
<td width="30%"><strong>success </strong>[<em>function(ele)</em>] (false)</td>
<td>Callback for when an image has loaded. <a href="#Callback">Go to callback example</a></td>
</tr>
<tr>
<td width="30%"><b>successClass </b>[<em>string</em>](‘b-loaded’)</td>
<td>The classname an element will get when loaded.</td>
</tr>
<tr>
<td width="30%"><b>validateDelay </b>[<em>int</em>](25)</td>
<td>Delay for how often it should call the validate function on scroll/resize. Default is 25ms.</td>
</tr>
</tbody>
</table>
<p>You pass the options as an object of key/value pairs:</p>
<pre> <span class="code-comment">// Format</span>
var bLazy = new <span class="code-function">Blazy</span>({
key: value
, key: value
, key: value
});</pre>
<h3 id="Offset">Selector</h3>
<p>You can change the selector if you don’t want to add the ‘b-lazy’ class or if you need to have multiple.</p>
<pre> <span class="code-comment">// Example</span>
var bLazy = new <span class="code-function">Blazy</span>({
selector: 'img' <span class="code-comment">// all images</span>
});</pre>
<h3 id="Offset">Offset</h3>
<p>The offset controls how early you want the elements to be loaded before they’re visible. Default is 100, so 100px before an element is visible it’ll start loading.</p>
<pre> <span class="code-comment">// Example</span>
var bLazy = new <span class="code-function">Blazy</span>({
offset: 100 <span class="code-comment">// Loads images 100px before they're visible</span>
});</pre>
<h3 id="Inside">Images inside a container</h3>
<p>You can also lazy load images inside a scrolling container, just define the selector of the container:</p>
<pre> <span class="code-comment">// Example</span>
var bLazy = new <span class="code-function">Blazy</span>({
container: '#scrolling-container' <span class="code-comment">// Default is window</span>
});</pre>
<h3 id="Callback">Callback when image has loaded or fails</h3>
<p>If you need to do anything when an image has loaded or fails you can pass a callback function:</p>
<pre> <span class="code-comment">// Example</span>
var bLazy = new <span class="code-function">Blazy</span>({
success: <span class="code-function">function</span>(ele){
<span class="code-comment">// Image has loaded</span>
<span class="code-comment">// Do your business here</span>
}
, error: <span class="code-function">function</span>(ele, msg){
if(msg === <span class="code-string">'missing'</span>){
<span class="code-comment">// Data-src is missing</span>
}
else if(msg === <span class="code-string">'invalid'</span>){
<span class="code-comment">// Data-src is invalid</span>
}
}
});</pre>
<h3 id="Retina">Retina images</h3>
<p>If you’re not doing <em>retina-first</em> don’t worry. It’s easy to serve retina images for retina displays. Just add the source to the retina image in the data-src by using the separator (default is ‘|’) and bLazy will do the rest:</p>
<pre> <img class=<span class="code-string">"b-lazy"</span>
src=<span class="code-string">data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==</span>
data-src=<span class="code-string">"image.jpg|retina-image.jpg"</span>
alt=<span class="code-string">"alt-text"</span>
/></pre>
<h3 id="Background">Background images</h3>
<p>You can also lazy load background images. If the element with the lazy load class (default: ‘.b-lazy’) isn’t an image, the source will be added to the element as a background image:</p>
<pre> <div class=<span class="code-string">"b-lazy"</span> data-src=<span class="code-string">"background-image.jpg"</span></div></pre>
<h3 id="Multi">Multi-serve images</h3>
<p>You can multi-serve images, so users on smaller devices will get a smaller image served and the page will load faster. If you have more than one it’s important that the widths are ascending like in my example; 420 comes before 768. If you set up a multi rule but your image markup doesn’t have the src attribute on it, it’ll look after the default src, data-src.</p>
<pre> <span class="code-comment">// Example</span>
var bLazy = new <span class="code-function">Blazy</span>({
breakpoints: [{
width: <span class="code-int">420</span> <span class="code-comment">// max-width</span>
, src: <span class="code-string">'data-src-small'</span>
}
, {
width: <span class="code-int">768</span> <span class="code-comment">// max-width</span>
, src: <span class="code-string">'data-src-medium'</span>
}]
});</pre>
<p>Image markup:</p>
<pre> <img class=<span class="code-string">"b-lazy"</span>
src=<span class="code-string">data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==</span>
data-src=<span class="code-string">"image.jpg"</span>
data-src-small=<span class="code-string">"image-small.jpg"</span>
data-src-medium=<span class="code-string">"image-medium.jpg"</span>
alt=<span class="code-string">"alt-text"</span>
/></pre>
<h3 id="Transitions">Image transitions</h3>
<p>Image transitions are not a built-in feature in bLazy.js but you can easily add it with css. When an image has loaded a loaded class (default: b-loaded) is added to the image, so you can add:</p>
<pre> <span class="code-function">.b-lazy</span> {
<span class="code-undefined">-webkit-transition</span>: opacity <span class="code-int">500</span>ms ease-in-out;
<span class="code-undefined">-moz-transition</span>: opacity <span class="code-int">500</span>ms ease-in-out;
<span class="code-undefined">-o-transition</span>: opacity <span class="code-int">500</span>ms ease-in-out;
<span class="code-undefined">transition</span>: opacity <span class="code-int">500</span>ms ease-in-out;
<span class="code-undefined">max-width</span>: <span class="code-int">100</span>%;
<span class="code-undefined">opacity</span>: <span class="code-int">0</span>;
}
<span class="code-function">.b-lazy.b-loaded</span> {
<span class="code-undefined">opacity</span>: <span class="code-int">1</span>;
}</pre>
<h3 id="Functions">Public functions</h3>
<table style="border: 0px none;" border="0" width="100%">
<tbody>
<tr>
<td style="background-color: #1e1e1e;" colspan="2"><span style="color: #ffffff;"><b>Public functions</b></span></td>
</tr>
<tr>
<td width="30%"><strong>revalidate()</strong></td>
<td>Revalidates document for visible images. Useful if you add images with scripting or ajax</td>
</tr>
<tr>
<td width="30%"><strong>load(</strong>element(s), force<strong>)</strong></td>
<td>Forces the given element(s) to load if not collapsed. If you also want to load a collapsed/hidden elements you can add <em>true</em> as the second parameter.<br>
You can pass a single element or a list of elements. Tested with getElementById, getElementsByClassName, querySelectorAll, querySelector and jQuery selector.</td>
</tr>
<tr>
<td width="30%"><b>destroy()</b></td>
<td>Unbind events and resets image array</td>
</tr>
</tbody>
</table>
<pre> <span class="code-comment">// Example</span>
var bLazy = new <span class="code-function">Blazy</span>();
bLazy.<span class="code-function">functionName</span>(); <span class="code-comment">// eg bLazy.revalidate();</span></pre>
<h3 id="Responsive">Responsive images</h3>
<p>An example on how to lazy load and multi-serve responsive images without having the page reflow.</p>
<p>Markup:</p>
<pre> <div class=<span class="code-string">"image-wrapper ratio_16-9"</span>>
<img class=<span class="code-string">"b-lazy"</span>
src=<span class="code-string">data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==</span>
data-src=<span class="code-string">"image.jpg"</span>
data-src-small=<span class="code-string">"image-small.jpg"</span>
alt=<span class="code-string">"alt-text"</span>
/>
<!-- <span class="code-comment">Fallback for non JavaScript browsers</span> -->
<noscript><img src=<span class="code-string">"image.jpg"</span> alt=<span class="code-string">"alt-text"</span> /></noscript>
</div></pre>
<p>CSS:</p>
<pre> <span class="code-function">.image-wrapper</span> {
<span class="code-comment">// Adding a loader and background color. The user will see it</span>
<span class="code-comment">// if the image is loading slow.</span>
<span class="code-undefined">background</span>: #1E1E1E url(<span class="code-string">'loader.gif'</span>) center center no-repeat;
<span class="code-undefined">width</span>: <span class="code-int">100</span>%
}
<span class="code-function">.ratio_16-9</span> {
<span class="code-comment">// The image has a 16/9 ratio. Until the image has loaded</span>
<span class="code-comment">// we need to reserve some space so the page won't reflow.</span>
<span class="code-comment">// How to calculate the space (padding-bottom): 9/16*100 = 56.25</span>
<span class="code-comment">// Another example: you have an image 400x250.</span>
<span class="code-comment">// So if you want to calculate the space you do: 250/400*100 = 62.5</span>
<span class="code-undefined">padding-bottom</span>: <span class="code-int">56.25</span>%;
<span class="code-undefined">height</span>: <span class="code-int">0</span>;
}
<span class="code-function">.b-lazy</span> {
<span class="code-undefined">max-width</span>: <span class="code-int">100</span>%;
}</pre>
<h3 id="iframe">Iframes, unity games etc.</h3>
<p>With blazy.js you can lazy load everything with a src attribute, not only images. For example iframes:</p>
<pre class="brush: html line-numbers language-html"><code class=" language-html"><span class="token tag"><span class="token punctuation"><</span>iframe class="<span class="code-string">b-lazy</span>" data-<span class="token attr-name">src</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span><span class="code-string">page.html</span><span class="token punctuation">"</span></span> <span class="token attr-name">width</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span><span class="code-string">300</span><span class="token punctuation">"</span></span> <span class="token attr-name">height</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span><span class="code-string">300</span><span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token punctuation"><</span>p<span class="token punctuation">></span></span><span class="code-comment">Your browser does not support iframes.</span><span class="token tag"><span class="token punctuation"></</span>p<span class="token punctuation">></span></span>
<span class="token tag"><span class="token punctuation"></</span>iframe<span class="token punctuation">></span></span></code></pre>
<h3 id="angular">With AngularJS</h3>
<p>Some users have asked if they can use blazy.js together with angular.js. The short answer is yes. Blazy.js is just plain javascript why you of course can do that. However since angular strippes the <code>data-</code>prefix from attribute names as part of the directive-name normalization process you either need to:</p>
<ul>
<li>change the default <em>data-src</em> name because otherwise it’s like setting two src’s and firefox and chrome handles that differently.</li>
<li>or don’t have any default src.</li>
</ul>
<pre><span class="code-comment">// Example</span>
var bLazy = new <span class="code-function">Blazy</span>({
src: 'data-blazy' <span class="code-comment">// Default is data-src</span>
});
//Markup
<img class=<span class="code-string">"b-lazy"</span>
src=<span class="code-string">"placeholder-image.jpg"</span>
<strong>data-blazy</strong>=<span class="code-string">"image.jpg"</span>
alt=<span class="code-string">"alt-text"</span>
/></pre>
<p>or</p>
<pre><img class=<span class="code-string">"b-lazy"</span> data-src=<span class="code-string">"image.jpg" </span>alt=<span class="code-string">"alt-text" </span>/></pre>
<h3 id="license">License</h3>
<p>bLazy is licensed under <strong>MIT</strong> and the <strong>DWIWYWBPVMS</strong> license. (Do With It What You Want But Please Visit My Sponsor).</p>
<h3 id="Support">Support</h3>
<p>Support bLazy by visiting my sponsor:</p>
<div class="sponsor">
<p><script>// <![CDATA[
google_ad_client = "ca-pub-3114094015984236"; /* dinbror bPopup blog */ google_ad_slot = "7720481863"; google_ad_width = 468; google_ad_height = 60; // ]]>
// ]]></script><script src="http://pagead2.googlesyndication.com/pagead/show_ads.js">// <![CDATA[
// ]]>
// ]]></script><ins id="aswift_0_expand" style="display:inline-table;border:none;height:60px;margin:0;padding:0;position:relative;visibility:visible;width:468px;background-color:transparent"><ins id="aswift_0_anchor" style="display:block;border:none;height:60px;margin:0;padding:0;position:relative;visibility:visible;width:468px;background-color:transparent"><iframe width="468" height="60" frameborder="0" marginwidth="0" marginheight="0" vspace="0" hspace="0" allowtransparency="true" scrolling="no" allowfullscreen="true" onload="var i=this.id,s=window.google_iframe_oncopy,H=s&&s.handlers,h=H&&H[i],w=this.contentWindow,d;try{d=w.document}catch(e){}if(h&&d&&(!d.body||!d.body.firstChild)){if(h.call){setTimeout(h,0)}else if(h.match){try{h=s.upd(h,i)}catch(e){}w.location.replace(h)}}" id="aswift_0" name="aswift_0" style="left:0;position:absolute;top:0;"></iframe></ins></ins></p>
</div>
</div>