Skip to content

Commit 8823995

Browse files
author
Andrea Verlicchi
committed
Merge branch 'release/15.0.0'
2 parents 1a7cbd1 + 71e323d commit 8823995

23 files changed

+1132
-595
lines changed

‎CHANGELOG.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,20 @@
11
# CHANGELOG
22

3+
## Version 15
4+
5+
#### 15.0.0
6+
7+
**Lazy background images gained loaded/error classes and callbacks! 🎉**
8+
9+
**Breaking changes impacting lazy background images!** ⚠ See [UPGRADE.md](UPGRADE.md) to understand **if** you are impacted and **how** to upgrade from previous versions.
10+
11+
- Lazy loading of **one background image** using the `data-bg` attribute, now manages the `load` and `error` events, so they are applied the classes defined in the `class_loading`/`class_loaded`/`class_error`, and the callbacks defined in `callback_loading`/`callback_loaded`/`callback_error`.
12+
- Lazy loading of **multiple background images** is still possible via the `data-bg-multi` attribute. In this case, the `load` and `error` events are not managed. The `class_applied` and `callback_applied` can be used to understand when the multiple background was applied to the element.
13+
- Updated background images demos:
14+
- background-images.html -> single background images
15+
- background-images-multi.html -> multiple background images
16+
- Added [UPGRADE.md](UPGRADE.md), a guide on how to upgrade from previous versions (from version 12 up)
17+
318
## Version 14
419

520
#### 14.0.1

‎README.md‎

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -76,22 +76,24 @@ To have a low quality placeholder, add the `src` attribute pointing to a very sm
7676
Single background
7777

7878
```html
79-
<div class="lazy" data-bg="url(lazy.jpg)"></div>
79+
<div class="lazy" data-bg="lazy.jpg"></div>
8080
```
8181

8282
Multiple backgrounds
8383

8484
```html
85-
<div class="lazy" data-bg="url(lazy-head.jpg), url(lazy-body.jpg), linear-gradient(#fff, #ccc)">
85+
<div
86+
class="lazy"
87+
data-bg-multi="url(lazy-head.jpg), url(lazy-body.jpg), linear-gradient(#fff, #ccc)"
88+
>
8689
...
8790
</div>
8891
```
8992

9093
Notes:
9194

92-
- you need to use `url()` in the value of your `data-bg` attribute, also for single background
93-
- you shouldn't use background images to load content images, they're bad for SEO and for accessibility
94-
- on background images, `callback_loaded` won't be called and the `class_loaded` class won't be added
95+
- you need to use `url()` in the values of your `data-bg-multi` attribute
96+
- ⚠ you shouldn't use background images to load content images, they're bad for SEO and for accessibility
9597

9698
#### Lazy video
9799

@@ -113,7 +115,9 @@ Please note that the video poster can be lazily loaded too.
113115

114116
## 👩‍💻 Getting started - Script
115117

116-
The latest, recommended version of LazyLoad is **14.0.1**.
118+
The latest, recommended version of LazyLoad is **15.0.0**.
119+
120+
Quickly understand how to upgrade from a previous version reading the [practical upgrade guide](UPGRADE.md).
117121

118122
### To polyfill or not to polyfill IntersectionObserver?
119123

@@ -128,14 +132,14 @@ If you prefer to load a polyfill, the regular LazyLoad behaviour is granted.
128132
The easiest way to use LazyLoad is to include the script from a CDN:
129133

130134
```html
131-
<script src="https://cdn.jsdelivr.net/npm/vanilla-lazyload@14.0.1/dist/lazyload.min.js"></script>
135+
<script src="https://cdn.jsdelivr.net/npm/vanilla-lazyload@15.0.0/dist/lazyload.min.js"></script>
132136
```
133137

134138
Or, with the IntersectionObserver polyfill:
135139

136140
```html
137141
<script src="https://cdn.jsdelivr.net/npm/[email protected]/intersection-observer.js"></script>
138-
<script src="https://cdn.jsdelivr.net/npm/vanilla-lazyload@14.0.1/dist/lazyload.min.js"></script>
142+
<script src="https://cdn.jsdelivr.net/npm/vanilla-lazyload@15.0.0/dist/lazyload.min.js"></script>
139143
```
140144

141145
Then, in your javascript code:
@@ -168,7 +172,7 @@ Include RequireJS:
168172
Then `require` the AMD version of LazyLoad, like this:
169173

170174
```js
171-
var lazyLoadAmdUrl = "https://cdn.jsdelivr.net/npm/vanilla-lazyload@14.0.1/dist/lazyload.amd.min.js";
175+
var lazyLoadAmdUrl = "https://cdn.jsdelivr.net/npm/vanilla-lazyload@15.0.0/dist/lazyload.amd.min.js";
172176
var polyfillAmdUrl = "https://cdn.jsdelivr.net/npm/[email protected]/intersection-observer-amd.js";
173177

174178
/// Dynamically define the dependencies
@@ -214,7 +218,7 @@ Then include the script.
214218
```html
215219
<script
216220
async
217-
src="https://cdn.jsdelivr.net/npm/vanilla-lazyload@14.0.1/dist/lazyload.min.js"
221+
src="https://cdn.jsdelivr.net/npm/vanilla-lazyload@15.0.0/dist/lazyload.min.js"
218222
></script>
219223
```
220224
@@ -247,7 +251,7 @@ Then include the script.
247251
```html
248252
<script
249253
async
250-
src="https://cdn.jsdelivr.net/npm/vanilla-lazyload@14.0.1/dist/lazyload.min.js"
254+
src="https://cdn.jsdelivr.net/npm/vanilla-lazyload@15.0.0/dist/lazyload.min.js"
251255
></script>
252256
```
253257
@@ -622,18 +626,21 @@ Here's the list of the options.
622626
| `elements_selector` | The CSS selector of the elements to load lazily, which will be selected as descendants of the `container` object. | `"img"` | `".images img.lazy"` |
623627
| `threshold` | A number of pixels representing the outer distance off the scrolling area from which to start loading the elements. | `300` | `0` |
624628
| `thresholds` | Similar to `threshold`, but accepting multiple values and both `px` and `%` units. It maps directly to the `rootMargin` property of IntersectionObserver ([read more](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/rootMargin)), so it must be a string with a syntax similar to the CSS `margin` property. You can use it when you need to have different thresholds for the scrolling area. It overrides `threshold` when passed. | `null` | `"500px 10%"` |
625-
| `data_src` | The name of the data attribute containing the original image source, excluding the `"data-"` part. E.g. if your data attribute is named `"data-src"`, just pass `"src"` | `"src"` | `"lazy-src"` |
626-
| `data_srcset` | The name of the data attribute containing the original image source set in either `img` and `source` tags, excluding the `"data-"` part. E.g. if your data attribute is named `"data-srcset"`, just pass `"srcset"` | `"srcset"` | `"lazy-srcset"` |
629+
| `data_src` | The name of the data attribute containing the element source to load, excluding the `"data-"` part. E.g. if your data attribute is named `"data-src"`, just pass `"src"` | `"src"` | `"lazy-src"` |
630+
| `data_srcset` | The name of the data attribute containing the image source set to load, in either `img` and `source` tags, excluding the `"data-"` part. E.g. if your data attribute is named `"data-srcset"`, just pass `"srcset"` | `"srcset"` | `"lazy-srcset"` |
627631
| `data_sizes` | The name of the data attribute containing the sizes attribute to use, excluding the `"data-"` part. E.g. if your data attribute is named `"data-sizes"`, just pass `"sizes"` | `"sizes"` | `"lazy-sizes"` |
628632
| `data_bg` | The name of the data attribute containing the value of `background-image` to load lazily, excluding the `"data-"` part. E.g. if your data attribute is named `"data-bg"`, just pass `"bg"`. The attribute value must be a valid value for `background-image`, including the `url()` part of the CSS instruction. | `"bg"` | `"lazy-bg"` |
633+
| `data_bg_multi` | The name of the data attribute containing the value of multiple `background-image` to load lazily, excluding the `"data-"` part. E.g. if your data attribute is named `"data-bg-multi"`, just pass `"bg-multi"`. The attribute value must be a valid value for `background-image`, including the `url()` part of the CSS instruction. | `"bg-multi"` | `"lazy-bg-multi"` |
629634
| `data_poster` | The name of the data attribute containing the value of `poster` to load lazily, excluding the `"data-"` part. E.g. if your data attribute is named `"data-poster"`, just pass `"poster"`. | `"poster"` | `"lazy-poster"` |
635+
| `class_applied` | The class applied to the multiple background elements after the multiple background was applied | `"applied"` | `"lazy-applied"` |
630636
| `class_loading` | The class applied to the elements while the loading is in progress. | `"loading"` | `"lazy-loading"` |
631637
| `class_loaded` | The class applied to the elements when the loading is complete. | `"loaded"` | `"lazy-loaded"` |
632638
| `class_error` | The class applied to the elements when the element causes an error. | `"error"` | `"lazy-error"` |
633639
| `load_delay` | The time (in milliseconds) each image needs to stay inside the viewport before its loading begins. | `0` | `300` |
634640
| `auto_unobserve` | A boolean that defines whether or not to automatically unobserve elements that was already revealed | `true` | `false` |
635641
| `callback_enter` | A callback function which is called whenever an element enters the viewport. Arguments: DOM element, intersection observer entry, lazyload instance. | `null` | `(el)=>{console.log("Entered", el)}` |
636642
| `callback_exit` | A callback function which is called whenever an element exits the viewport. Arguments: DOM element, intersection observer entry, lazyload instance. | `null` | `(el)=>{console.log("Exited", el)}` |
643+
| `callback_applied` | A callback function which is called whenever a multiple background element starts loading. Arguments: DOM element, lazyload instance. | `null` | `(el)=>{console.log("Applied", el)}` |
637644
| `callback_loading` | A callback function which is called whenever an element starts loading. Arguments: DOM element, lazyload instance. | `null` | `(el)=>{console.log("Loading", el)}` |
638645
| `callback_reveal` | **⚠ DEPRECATED: use `callback_loading` instead.** A callback function which is called whenever an element starts loading. Arguments: DOM element, lazyload instance. | `null` | `(el)=>{console.log("Loading", el)}` |
639646
| `callback_loaded` | A callback function which is called whenever an element finishes loading. Note that, in version older than 11.0.0, this option went under the name `callback_load`. Arguments: DOM element, lazyload instance. | `null` | `(el)=>{console.log("Loaded", el)}` |

‎UPGRADE.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# 🗺 HOW TO UPDATE FROM PREVIOUS VERSIONS
2+
3+
## Version 14 to 15
4+
5+
**If you have background images loaded via `data-src`**
6+
7+
You should replace `data-src` with `data-bg` in your markup/DOM
8+
9+
```html
10+
<!-- FROM -->
11+
<div data-src="background.jpg">...</div>
12+
<!-- TO -->
13+
<div data-bg="background.jpg">...</div>
14+
```
15+
16+
Alternatively, you could pass `src` in the `data_bg` option
17+
18+
```js
19+
new LazyLoad({ /* other options? */ data_bg: "src" });
20+
```
21+
22+
**If you have single background images loaded via `data-bg`**
23+
24+
You must remove the `url()` part from the `data-bg` attribute values
25+
26+
```html
27+
<!-- FROM -->
28+
<div data-bg="url(background.jpg)">...</div>
29+
<!-- TO -->
30+
<div data-bg="background.jpg">...</div>
31+
```
32+
33+
**If you have multipe background images loaded via `data-bg`**
34+
35+
You must change the attribute to `data-bg-multi`
36+
37+
```html
38+
<!-- FROM -->
39+
<div data-bg="url(background1.jpg), url(background2.jpg)">...</div>
40+
<!-- TO -->
41+
<div data-bg-multi="url(background1.jpg), url(background2.jpg)">...</div>
42+
```
43+
44+
## Version 13 to 14
45+
46+
**If you are using `callback_reveal`**
47+
48+
You should replace it to `callback_loading`. `callback_reveal` still works but it will be removed in next versions
49+
50+
```js
51+
// FROM
52+
new LazyLoad({ /* other options? */ callback_reveal: () => {} });
53+
// TO
54+
new LazyLoad({ /* other options? */ callback_loading: () => {} });
55+
```
56+
57+
## Version 12 to 13
58+
59+
**If you are using `callback_set`**
60+
61+
You should replace it to `callback_reveal`. `callback_set` still works but it will be removed in next versions
62+
63+
```js
64+
// FROM
65+
new LazyLoad({ /* other options? */ callback_set: () => {} });
66+
// TO
67+
new LazyLoad({ /* other options? */ callback_reveal: () => {} });
68+
```

0 commit comments

Comments
 (0)