Documentation.

Author: fabianmichael

assets/js/dist/imageset.js

@@ -1336,7 +1336,8 @@
 
       debouncedCheckImagesets();
     } else {
-      checkImagesets();
+      // If autoUpdate is disabled, check imagesets just once.
+      ready(checkImagesets);
     }
 
     return {

assets/js/dist/imageset.min.js

@@ -740,7 +740,8 @@
 
       debouncedCheckImagesets();
     } else {
-      checkImagesets();
+      // If autoUpdate is disabled, check imagesets just once.
+      ready(checkImagesets);
     }
 
     return {

assets/js/src/imageset.js

@@ -1,7 +1,13 @@
 # ImageSet Changelog
 
-- unversioned
-  - Fix mosaic placeholder rendering rendered too small.
+- `1.1.0-beta1` (2017/09/08)
+  - [Fix] Fix mosaic placeholder rendering rendered too small.
+  - [Fix] Remove double-loading settings from config
+  - [Feature] Add JavaScript configuration and API
+  - [Enhancement] Better error message when thumbs directory is missing.
+  - [Feature] Display a broken file icon, when an image couldn’t be loaded and display alt text, if provided.
+  - [Enhancement] Make all placeholder sources inline again to guarantee instand placeholder rendering after page load. This increases the initial HTML payload a bit, but results in fewer requests afterwards.
+  - [Fix] Using the color placeholder style on a completely transparent image will not cause the plugin to fail any more.
 
 - `1.0.1` (2017/03/22)
   - Fixes a problem that caused the dynamic presets API to throw a fatal error.

changelog.md

@@ -59,12 +59,13 @@ A flexible, responsive image component for [Kirby CMS](http://getkirby.com), fea
 - **Responsive Images** Add responsive images in different sizes to your website with ease by using ImageSet’s convenient template API.
 - **Easy to Use** ImageSet provides a convenient API for generating responsive image sets and also works with Kirbytext.
 - **Lazy Loading** It supports lazy loading for saving valuable bandwidth (especially on mobile) and faster page loads for everyone.*
--  **Placeholders & Ratios** ImageSet comes with placeholders in 4 beautiful styles and reserves screen space for images to avoid reflows (aka *page-jumps*) while the page is being loaded.
+-  **Placeholders & Ratios** ImageSet comes with placeholders in 5 beautiful styles and reserves screen space for images to avoid reflows (aka *page-jumps*) while the page is being loaded.
 -  **Art Direction** Define different sizes and crop ratios for different screen sizes and/or media types.
 -  **Progressive Enhancement** In case of doubt, the plugin works without JavaScript or native support for responsive images as a conditionally loaded polyfill is included for older browsers.
 -  **Web Standards** ImageSet produces HTML5-based markup (using the `<picture>` element and `srcset`-attribute).
--  **Works with AJAX** ImageSet works with dynamic content, as new imagesets are automatically detected and handled.
--  **Small Footprint** Frontend code has been designed for performance and comes with a minimal footprint. Only ~0,7 kB CSS + ~7,5 kB JavaScript (+ 5,7 kB Polyfill for older browsers), when minified & gzipped.
+-  **Works with AJAX** ImageSet works with dynamic content, as new image sets are automatically detected and handled.
+**Error Handling** When an image could not be loaded (e.g. due to a connection error), the plugin will display a broken image icon and alt text if supplied.
+-  **Small Footprint** Frontend code has been designed for performance and comes with a minimal footprint. Only ~1,5 kB CSS + ~7,5 kB JavaScript (+ 5,7 kB Polyfill for older browsers), when minified & gzipped.
 
 *) Lazy loading uses the very performant [lazysizes](https://github.com/aFarkas/lazysizes) script and requires JavaScript to be activated on the client. However, the plugin provides a `<noscript>`-fallback which is enabled by default.
 
@@ -133,7 +134,7 @@ In order to make ImageSet work properly, you have to include the corresponding C
 <?= css('assets/plugins/imageset/css/imageset.min.css') ?>
 ```
 
-If you use lazy loading, also add the following line anywhere after the previous code in your template, it is recommended to include the file before the closing `</head>` tag to ensure that it loads as fast as possible.
+If you use lazy loading, also add the following line anywhere after the previous code in your template, it is recommended to include the file before the closing `</head>` tag to ensure that it loads as fast as possible. If this is not possible, you can also include the script right before the closing body tag, but this lreads to later execution and can easily result in the flashing of un-rendered placeholders.
 
 ```php
 <?= js('assets/plugins/imageset/js/dist/imageset.js') ?>
@@ -153,12 +154,31 @@ Not all browsers are providing [native support](http://caniuse.com/#feat=picture
 </script>
 ```
 
-
-
 Alright, your site should now be prepared for using ImageSet! :-D
 
 <table><tr><td>ℹ️ For a dev environment or low-traffic sites, it is completely fine to link plugin assets directly. However, if performance is critical for your project, it is highly recommended to place a copy of the JS and CSS files linked above in your <code>assets</code> directory and link to them or to bundle up these assets with your regular CSS and JavaScript using the build tool of your choice.</td></tr></table>
 
+### 2.4 JavaScript Configuration & API
+
+✳️ Available from 1.1.0+
+
+ImageSet does everything automagically, from rendering placeholders to detecting dynamically added image sets. However, there might be some use-cases where you need a bit more control over how the ImageSet plugin works. Configuration is done by settings the global `window.imagesetConfig` variable before loading `imageset.js`. The plugin also exposes a global `imageset` variable to the window object, which is used for calling API methods (currently the only available method is `imageset.update()`).
+
+```html
+<script>
+window.imagesetConfig = {
+  autoUpdate: true,
+  placeholderRendering: 'async',
+};
+</script>
+<!-- include imageset.js after setting up configuration -->
+```
+
+| Option | Default value | Possible values | Description |
+|:--------------------|:--------------|:--------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `autoUpdate` | `true` | `true`, `false` | If enabled , ImageSet searches for new imagesets whenever the DOM updates. On pages with lots of animations, you might want to prevent that placeholders are being rendered during animations to keep those as smooth as possible. If this setting is disabled, you have to call `imageset.update()` manually after updating the DOM. |
+| `placeholderRendering` | `'async'` | `'async'`, `'sync'` | `async` Placeholders are rendered using `requestAnimationFrame()` where available, rendering only one placeholder every frame. On long pages with lots of large images, this keeps the browser responding while the page is being loaded, but can possibly result in the flash of un-rendered placeholders.<br>`sync` Placeholders are rendered immediately after new imagesets are detected. Use this setting when a large amount of smaller imagesets is visible above the fold or when placeholder-rendering could otherwise interfere with animations. |
+
 ## 3 Global Configuration
 
 The settings listed below are meant to be defined in your `config.php` and change the global behavior of the plugin. To learn about configuring the default behavior of image sets in your templates (lazy loading, placeholders, fallback behavior etc.), have a look at [4.3.1 Available Options](#431-available-options).