121 lines
5.6 KiB
Markdown
121 lines
5.6 KiB
Markdown
|
|
***
|
|
## <a name="faq"></a>FAQ
|
|
|
|
### CURRENT DEVELOPMENT STATUS
|
|
A full release should be reasonable after proper feedback from the community,
|
|
some code cleanup, and optimization where needed. Patches are very much welcome.
|
|
|
|
|
|
### PROGRAMATICALLY
|
|
[blazy.api.php](https://git.drupalcode.org/project/blazy/blob/8.x-2.x/blazy.api.php)
|
|
|
|
|
|
### BLAZY VS. B-LAZY
|
|
`blazy` is the module namespace. `b-lazy` is the default CSS class to lazy load.
|
|
|
|
* The `blazy` class is applied to the **top level container**, e,g.. `.field`,
|
|
`.view`, `.item-list`, etc., those which normally contain item collection.
|
|
In this container, you can feed any `bLazy` script options into `[data-blazy]`
|
|
attribute to override existing behaviors per particular page, only if needed.
|
|
* The `b-lazy` class is applied to the **target item** to lazy load, normally
|
|
the children of `.blazy`, but not always. This can be IMG, VIDEO, DIV, etc.
|
|
|
|
### WHAT `BLAZY` CSS CLASS IS FOR?
|
|
Aside from the fact that a module must reserve its namespace including for CSS
|
|
classes, the `blazy` is actually used to limit the scope to scan document.
|
|
Rather than scanning the entire DOM, you limit your work to a particular
|
|
`.blazy` container, and these can be many, no problem. This also allows each
|
|
`.blazy` container to have unique features, such as ones with multi-breakpoint
|
|
images, others with regular images; ones with a lightbox, others with
|
|
image to iframe; ones with CSS background, others with regular images; etc.
|
|
right on the same page. This is only possible and efficient within the `.blazy`
|
|
scope.
|
|
|
|
### WHY NOT `BLAZY__LAZY` FOR `B-LAZY`?
|
|
`b-lazy` is the default CSS class reserved by JS script. Rather than recreating
|
|
a new one, respecting the defaults is better. Following BEM standard is not
|
|
crucial for most JS generated CSS classes. Uniqueness matters.
|
|
|
|
### NATIVE LAZY LOADING
|
|
Blazy library last release was v1.8.2 (2016/10/25). 3 years later,
|
|
Native lazy loading is supported by Chrome 76+ as of 01/2019. Blazy or IO will
|
|
be used as fallback for other browsers instead. Currently the offset/ threshold
|
|
before loading is hard-coded to [8000px at Chrome](https://cs.chromium.org/chromium/src/third_party/blink/renderer/core/frame/settings.json5?l=971-1003&rcl=e8f3cf0bbe085fee0d1b468e84395aad3ebb2cad),
|
|
so it might only be good for super tall pages for now, be aware.
|
|
[Read more](https://web.dev/native-lazy-loading/)
|
|
|
|
This also may trick us to think lazy load not work, check out browsers' Network
|
|
tab to verify that it still does work.
|
|
|
|
**UPDATE 2020-04-24**: Added a delay to only lazy load once the first found is
|
|
loaded, see [#3120696](https://drupal.org/node/3120696)
|
|
|
|
**UPDATE 2022-01-22**:
|
|
With bIO as the main lazyloader, the game changed, quoted from:
|
|
https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Author_fast-loading_HTML_pages
|
|
> Note that lazily-loaded images may not be available when the load event is
|
|
fired. You can determine if a given image is loaded by checking to see if
|
|
the value of its Boolean complete property is true.
|
|
|
|
Old bLazy relies on `onload`, meaning too early loaded decision for Native,
|
|
the reason for our previous deferred invocation, not `decoding` like what bIO
|
|
did which is more precise as suggested by the quote.
|
|
|
|
Assumed, untested, fine with combo IO + `decoding` checks before blur spits.
|
|
|
|
Shortly we are in the right direction to cope with Native vs. `data-[SRC]`.
|
|
See `bio.js ::natively` for more contextual info.
|
|
[x] Todo recheck IF wrong so to put back https://drupal.org/node/3120696.
|
|
|
|
**UPDATE 2022-03-03**: The above is almost not wrong as proven by no `b-loaded`
|
|
class and no `blur` is triggered earlier, but 8000px threshold rules. Meaning
|
|
the image is immediately requested 8000px before entering viewport.
|
|
Added back a delay to only lazy load once the first found is loaded at field
|
|
formatter level via `Loading priority: defer`, see
|
|
[#3120696](https://drupal.org/node/3120696)
|
|
|
|
### ANIMATE.CSS INTEGRATION
|
|
Blazy container (`.media`) can be animated using
|
|
[animate.css](https://github.com/daneden/animate.css). The container is chosen
|
|
to be the animated element so to support various use cases:
|
|
CSS background, picture, image, or rich media contents.
|
|
|
|
See [GridStack](https://drupal.org/project/gridstack) 2.6+ for the `animate.css`
|
|
samples at Layout Builder pages.
|
|
|
|
To replace **Blur** effect with `animate.css` thingies, implements two things:
|
|
1. **Globally**: `hook_blazy_image_effects_alter` and add `animate.css` classes
|
|
to make them available for select options at Blazy UI.
|
|
2. **Fine grained**: `hook_blazy_settings_alter`, and replace a setting named
|
|
`fx` with one of `animate.css` CSS classes, adjust conditions based settings.
|
|
|
|
#### Requirements:
|
|
|
|
* The `animate.css` library included in your theme, or via `animate_css` module.
|
|
* Data attributes: `data-animation`, with optional: `data-animation-duration`,
|
|
`data-animation-delay` and `data-animation-iteration-count`, as seen below.
|
|
|
|
```
|
|
function MYTHEME_preprocess_blazy(&$variables) {
|
|
$settings = &$variables['settings'];
|
|
$attributes = &$variables['attributes'];
|
|
$blazies = &$settings['blazies'];
|
|
|
|
// Be sure to limit the scope, only animate for particular conditions.
|
|
if ($blazies->get('entity.id') == 123
|
|
&& $blazies->get('field.name') == 'field_media_animated') {
|
|
$fx = $blazies->get('fx');
|
|
|
|
// This was taken care of by feeding $fx, or hard-coded here.
|
|
$attributes['data-animation'] = $fx ?: 'wobble';
|
|
|
|
// The following can be defined manually.
|
|
$attributes['data-animation-duration'] = '3s';
|
|
$attributes['data-animation-delay'] = '.3s';
|
|
// Iteration can be any number, or infinite.
|
|
$attributes['data-animation-iteration-count'] = 'infinite';
|
|
}
|
|
}
|
|
```
|