# CONTENTS OF THIS FILE
* [Introduction](#introduction)
* [Requirements](#requirements)
* [Recommended modules](#recommended-modules)
* [Installation](#installation)
* [Configuration](#configuration)
* [Features](#features)
* [Updating](#updating)
* [Troubleshooting](#troubleshooting)
* [FAQ](#faq)
* [Aspect ratio template](#aspect-ratio-template)
* [Contribution](#contribution)
* [Maintainers](#maintainers)
.
***
***
.
# INTRODUCTION
Provides integration with bLazy and or Intersection Observer API to lazy load
and multi-serve images to save bandwidth and server requests. The user will have
faster load times and save data usage if they don't browse the whole page.
.
***
***
.
# REQUIREMENTS
1. bLazy library:
* [Download bLazy](https://github.com/dinbror/blazy)
* Extract it as is, rename **blazy-master** to **blazy**, so the assets are:
+ **/sites/../libraries/blazy/blazy.min.js**
2. PHP 5.6+ (let us know if Blazy can go lower?)
3. Any of autoloader modules:
* [registry_autoload](https://www.drupal.org/project/registry_autoload)
* [psr0](https://www.drupal.org/project/psr0)
* [xautoload](https://www.drupal.org/project/xautoload)
* [autoload](https://www.drupal.org/project/autoload)
* Others?
Skip if you already one have, I meant, have one. If you have others, please
create a feature to include it in the module `hook_requirements()`. The order
implies the recommendation priority.
.
***
***
.
# INSTALLATION
[Installing Drupal 7 module](http://drupal.org/documentation/install/modules-themes/modules-7)
### Two steps below are crucial, otherwise Blazy complains missing dependencies:
1. Visit **/admin/modules** and install one of autoloader as mentioned above.
Save! Do not install Blazy, yet, since Blazy has no hard dependency on any.
The order above indicates priority. The first found will be locked.
You can install another, and uninstall the other which suits you better.
2. Install Blazy. Once an autoloader is installed, it will be locked for
Blazy usage later to avoid accidental removal.
As long as you stick to these 2 steps, it should be just fine like regular
modules with hard dependencies.
### Known issues:
* **autoload**: must run `drush aur` and `drush cc` on Blazy activation, or
fatal. The same procedure applies whenever blazy-related modules are
activated, or adding new classes. Especially during DEV, Alpha, Beta,
before RC. If not using drush, consider the other two:
**registry_autoload**, **xautoload**.
If any issue with other autoloaders, kindly let us know. Blazy doesn't have a
hard dependency on any, it is on your own discretion.
**At any rate, solution is available:**
* Before any update, open `/admin/config/development/performance`, so to clear
cache easily before running into issues.
* Know how to run `drush cc all` or clear cache.
* Only **at worst** case, clear registry, or if you don't drush, install and
know how to use registry_rebuild.module safely.
This particular issue never happens at D8, please bear with D7, and current
Blazy limitation and development process.
### WTF FTW?
Blazy uses classes as a direct backport of 8.x.
.
***
***
.
# FEATURES
* Supports core Image.
* Supports Picture.
* Supports Colorbox/ Photobox/ PhotoSwipe, etc, also multimedia lightboxes.
* Multi-serving lazyloaded images, including multi-breakpoint CSS backgrounds.
* Lazyload video iframe urls via custom coded, or Media.
* Supports inline images and iframes with lightboxes, and grid or CSS3 Masonry
via Blazy Filter. Enable Blazy filter at **/admin/config/content/formats**,
and check out instruction at **/filter/tips**.
* Blazy Grid formatter for Image, Media and Text with multi-value.
* Delay loading for below-fold images until 100px (configurable) before they are
visible at viewport.
* A simple effortless CSS loading indicator.
* It doesn't take over all images, so it can be enabled as needed via Blazy
formatters, or its supporting modules.
## OPTIONAL FEATURES
* Views fields for File Entity and Media integration, see Slick Browser.
* Views style plugin Blazy Grid for Grid Foundation or CSS3 Masonry.
* Field formatters: Blazy with Media integration.
.
***
***
.
# CONFIGURATION
Be sure to enable Blazy UI which can be uninstalled at production later.
* Go to Manage display page, e.g.:
[Admin page displays](/admin/structure/types/manage/page/display)
* Find **Blazy** formatter under **Manage display**.
* Go to [Blazy UI](/admin/config/media/blazy) to manage few global options,
including enabling support to bring Picture into blazy-related formatters.
### USAGES: BLAZY FOR MULTIMEDIA GALLERY VIA VIEWS UI
1. Add a Views style **Blazy Grid** for entities containing Media or Image.
2. Add a Blazy formatter for the Media or Image field.
3. Add any lightbox under **Media switcher** option.
4. Limit the values to 1 under **Multiple field settings** > **Display**.
5. Be sure to leave **Use field template** under **Style settings** unchecked.
If checked, the gallery is locked to a single entity, that is no Views
gallery, but gallery per field.
Check out the relevant sub-module docs for details.
.
***
***
.
# RECOMMENDED MODULES
* [Markdown](https://www.drupal.org/project/markdown)
To make reading this README a breeze at [Blazy help](/admin/help/blazy_ui)
## MODULES THAT INTEGRATE WITH OR REQUIRE BLAZY
* [Ajaxin](https://www.drupal.org/project/ajaxin)
* [Intersection Observer](https://www.drupal.org/project/io)
* [Blazy PhotoSwipe](https://www.drupal.org/project/blazy_photoswipe)
* [GridStack](https://www.drupal.org/project/gridstack)
* [Outlayer](https://www.drupal.org/project/outlayer)
* [Intense](https://www.drupal.org/project/intense)
* [Mason](https://www.drupal.org/project/mason)
* [Slick](https://www.drupal.org/project/slick)
* [Slick Lightbox](https://www.drupal.org/project/slick_lightbox)
* [Slick Views](https://www.drupal.org/project/slick_views)
* [Slick Paragraphs](https://www.drupal.org/project/slick_paragraphs)
* [Jumper](https://www.drupal.org/project/jumper)
* [Zooming](https://www.drupal.org/project/zooming)
* [ElevateZoom Plus](https://www.drupal.org/project/elevatezoomplus)
Most duplication efforts from the above modules will be merged into
\Drupal\blazy\Dejavu or anywhere else namespace.
**What dups?**
The most obvious is the removal of formatters from Intense, Zooming,
Slick Lightbox, Blazy PhotoSwipe, and other (quasi-)lightboxes. Any lightbox
supported by Blazy can use Blazy, or Slick formatters if applicable instead.
We do not have separate formatters when its prime functionality is embedding
a lightbox, or superceded by Blazy.
Blazy provides a versatile and reusable formatter for a few known lightboxes
with extra advantages:
lazyloading, grid, multi-serving images, Responsive image,
CSS background, captioning, etc.
Including making those lightboxes available for free at Views Field for
File entity, Media and Blazy Filter for inline images.
If you are developing lightboxes and using Blazy, I would humbly invite you
to give Blazy a try, and consider joining forces with Blazy, and help improve it
for the above-mentioned advantages. We are also continuously improving and
solidifying the API to make advanced usages a lot easier, and DX friendly.
Currently, of course, not perfect, but have been proven to play nice with at
least 7 lightboxes, and likely more.
## SIMILAR MODULES
[Lazyloader](https://www.drupal.org/project/lazyloader)
.
***
***
.
# MAINTAINERS/CREDITS
* [Gaus Surahman](https://www.drupal.org/user/159062)
* [Contributors](https://www.drupal.org/node/2663268/committers)
* CHANGELOG.txt for helpful souls with their patches, suggestions and reports.
## READ MORE
See the project page on drupal.org:
[Blazy module](http://drupal.org/project/blazy)
See the bLazy docs at:
* [Blazy library](https://github.com/dinbror/blazy)
* [Blazy website](http://dinbror.dk/blazy/)
.
***
***
.
# 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/7.x-1.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
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 [800px 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/)
## 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.
### 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'];
// Be sure to limit the scope, only animate for particular conditions.
if ($settings['entity_id'] == 123
&& $settings['field_name'] == 'field_media_animated') {
$attributes['data-animation'] = 'wobble';
$attributes['data-animation-duration'] = '3s';
$attributes['data-animation-delay'] = '.3s';
// Iteration can be any number, or infinite.
$attributes['data-animation-iteration-count'] = 'infinite';
}
}
```
## PERFORMANCE TIPS:
* If breakpoints provided with tons of images, using image styles with ANY crop
is recommended to avoid image dimension calculation with individual images.
The image dimensions will be set once, and inherited by all images as long as
they contain word crop. If using scaled image styles, regular calculation
applies.
.
.
***
***
.
# UPDATE SOP
Visit any of the following URLs when updating Blazy, or its related modules.
Please ignore any documentation if already aware of Drupal site building. This
is for the sake of completed documentation for those who may need it.
1. [Performance](/admin/config/development/performance)
Unless an update is required, clearing cache should fix most issues.
* Hit **Clear all caches** button once the new Blazy in place.
* Regenerate CSS and JS as the latest fixes may contain changes to the assets.
Ignore below if you are aware, and found no asset changes from commits.
Normally clearing cache suffices when no asset changes are found.
* Uncheck CSS and JS aggregation options under Bandwidth optimization.
* Save.
* [Ignorable] See one of Blazy related pages if display is expected.
* [Ignorable] Only clear cache if needed.
* Check both options again.
* Save again.
* [Ignorable] Press F5, or CMD/ CTRL + R to refresh browser cache if
needed.
2. [Admin status](/admin/reports/status)
Check for any pending update, and run /update.php from browser address bar.
3. If `theme_blazy()` is customized, compare against the latest.
4. Always test updates at DEV or STAGING environments like a pro so nothing
breaks your PRODUCTION site till everything is thoroughly reviewed.
5. Read more the [TROUBLESHOOTING](#troubleshooting) section for common trouble
solutions.
## BROKEN MODULES
Alpha, Beta, DEV releases are for developers only. Beware of possible breakage.
However if it is broken, unless an update is provided, running `drush cc` during
DEV releases should fix most issues as we add new services, or change things.
If you don't drush, before any module update:
1. Always open a separate tab:
[Performance](/admin/config/development/performance)
2. And so you are ready to hit **Clear all caches** button if any issue. Do not
reload this page.
3. Instead view other browser tabs, and simply hit the button if any
issue.
4. Run `/update.php` as required.
5. Only at worst case, know how to run
[Registry Rebuild](https://www.drupal.org/project/registry_rebuild) safely.
.
***
***
.
# TROUBLESHOOTING
* Blazy and its sub-modules -- Slick, GridStack, etc. are tightly coupled.
Be sure to have the latest release date or matching versions in the least.
DEV for DEV, Beta for Beta, etc. Mismatched versions may lead to errors
especially before having RCs. Mismatched branches will surely be errors.
* Resizing is not supported. Just reload the page.
* Images are gone, only eternal blue loader is flipping like a drunk butterfly.
Solution: ensures that blazy library is loaded. And temporarily switch to
stock Bartik themes.
* Press F12 at any browser, and see the errors at the browser console. Any JS
error will prevent Blazy from working identified by eternal blue loaders.
* Images are collapsed. Solution: choose one of the Aspect ratio.
* Images or videos aren't responsive. Solution: choose one of the Aspect ratio.
* Images are distorted. Solution: choose the correct Aspect ratio. If unsure,
choose "fluid" to let the module calculate aspect ratio automatically.
[Check out few aspect ratio samples](https://cgit.drupalcode.org/blazy/tree/docs/ASPECT_RATIO.md)
### 1. VIEWS INTEGRATION
Blazy provides a simple Views field for File Entity, and Media.
When using Blazy formatter within Views, check **Use field template** under
**Style settings**, if trouble with Blazy Formatter as a stand alone Views
output.
On the contrary, uncheck **Use field template**, when Blazy formatter
is embedded inside another module such as Slick so to pass the renderable
array to work with accordingly.
This is a Views common gotcha with field formatter, so be aware of it.
If confusing, just toggle **Use field template**, and see the output. You'll
know which works.
### 2. BLAZY GRID WITH SINGLE VALUE FIELD (D7 ONLY)
This is no issue at D8. Blazy Grid formatter is designed for multi-value fields.
Unfortunately no handy way to disable formatters for single value at D7. So
the formatter is available even for single value, but not actually
functioning. Please ignore it till we can get rid of it at D7, if possible,
without extra legs.
### 3. MIN-WIDTH
If the images appear to be shrink within a **floating** container, add
some expected width or min-width to the parent container via CSS accordingly.
Non-floating image parent containers aren't affected.
### 4. MIN-HEIGHT
Add a min-height CSS to individual element to avoid layout reflow if not using
**Aspect ratio** or when **Aspect ratio** is not supported such as with
Responsive image. Otherwise some collapsed image containers will defeat the
purpose of lazyloading. When using CSS background, the container may also be
collapsed.
### 5. SOLUTIONS
Both layout reflow and lazyloading delay issues are actually taken care of
if **Aspect ratio** option is enabled in the first place.
Adjust, and override blazy CSS/ JS files accordingly.
### 6. BLAZY FILTER
Blazy Filter must run after **Align/ Caption filters** as otherwise the required
CSS class `b-lazy` will be moved into `` elements and make Blazy fail
with JS error due to not finding the required `SRC` and `[data-src]` attributes.
**Align/ Caption filters** output are respected and moved into Blazy markups
accordingly when Blazy Filter runs after them.
**Note**: This is D8 only issue. However it may apply to D7 for similar filters.
### 7. INTERSECTION OBSERVER API
* **IntersectionObserver API** is not loading all images, try disabling
**Disconnect** option at Blazy UI.
* **IntersectionObserver API** is not working with Slick `slidesToShow > 1`, try
disabling Slick `centerMode`. If still failing, choose one of the 4 lazy
load options, except Blazy.
### 8. BROKEN MODULES
Alpha, Beta, DEV releases are for developers only. Beware of possible breakage.
However if it is broken, unless an update is provided, running `drush cr` during
DEV releases should fix most issues as we add new services, or change things.
If you don't drush, before any module update, always open a separate tab:
[Performance](/admin/config/development/performance)
And so you are ready to hit **Clear all caches** if any issue.
Only at worst case, know how to run
https://www.drupal.org/project/registry_rebuild safely.
.
***
***
.
# SUBMITTING PATCHES OR ISSUES
Please consider the following to help you explain better, and to help us
understand better your bug reports, or patches as needed:
1. [Issue summaries](https://www.drupal.org/issue-summaries)
2. [Issue template](https://www.drupal.org/node/1326662)
* If you hate formalism, consider a crystal clear line, or two in the body text.
* Avoid explaining everything in the title.
* Use body text for explanation purposes.
* If language is a barrier, use any available/ online translation tool.
### 1. SUBMITTING ISSUES
When submitting bug reports, please:
* be kind with proper reproduction, and enough details.
* mention library version, related-module version, if any, active theme, or
anything which may help us identify issue better.
* ensure the library is loaded, not 404.
* switch to stock (Responsive) Bartik for just in case it is your custom theme.
* switch to default formatters, image to Image, text to Default, etc.
* use matching or similar branches or tags for related modules.
* check out dups at project issues, your problem may be already addressed.
* consult descriptions on each form item.
* file it a support request, if unsure. We'll mark a bug a bug even if you
file it under support requests.
* Check out TROUBLESHOOTING section for more.
### 2. SUBMITTING PATCHES
We consider a patch as help, they consider it a sale, so thank you in advanced!
In order for you to help, or buy, us successfully, please consider:
* communicating and filling out the body text with proper explanations, not in
comments (unless for comment patches, of course).
I've seen patches which broke a module, so explanation is a must.
If you have no time to write it in the body text, please hold off till later!
* providing optional links to the change records, or docs, if any.
* providing links to docs is a must for coding standards issues.
This also lets us, you and me, learn from the actual docs, not told by tools!
We can just run `drupalcs ...`, but help is welcome, too, in case a miss.
* checking out the latest dev branch in case already resolved.
* providing reproduction steps for bug reports is a must. No repro, no bugs.
You must speak like human to human, and help us respect you, and your time.
Dumping patches with empty body text (no explanations, not even saying hi) will
be disregarded, till the above is met.
Thank you for your kind consideration, cooperation, and contribution!
.
***
***
.
# ASPECT RATIO TEMPLATE
## Tools to check aspect ratio:
http://size43.com/jqueryVideoTool.html
## Common resolutions:
http://en.wikipedia.org/wiki/List_of_common_resolutions
## Aspect ratio 4:3
* 640x480
* 800x600
* 1024x768
* 1152x864
* 1280x960
* 1400x1050
* 1600x1200
* 2048x1536
* 3200x2400
* 4000x3000
* 6400x4800
## Aspect ratio 16:9
* 640x360
* 853x480
* 960x540
* 1024x576
* 1280x720
* 1366x768
* 1600x900
* 1920x1080
* 2048x1152
* 2560x1440
* 2880x1620
* 3840x2160
* 4096x2304
* 7680x4320
## Aspect ratio 16:10
* 1440x900
* 1680x1050
* 1920x1200
* 2560x1600
* 3840x2400
* 7680x4800
.
***
***
.
# ISSUE TEMPLATE
## Please describe the issue in crystal-clear sentences:
(Steps to reproduce, if it is a bug/ support report.)
## Library versions:
(Blazy, Slick, etc.)
## Module versions, including its-submodules relevant to this issue:
(Blazy, Slick, Slick Views, etc. Ignore any irrelevant accordingly.)
## Default active theme:
(Responsive/ Bartik, custom.)
## Press F12 at any browser, and post the console output, if any error:
(Ignore if you don't see no evil.)
## Delete this line and anything below when submitting issue. This is just FYI:
This is just a generic catch-all issue template to help you explain better, and
to help us understand your issue better in a shortest possible time.
Be more specific, of course. Feel free to ignore or delete any irrelevant step,
or be more innovative. A crystal-clear line or two is also very much welcome.
It doesn't dictate, it should help us be on the same page, and narrows down.
### Before you proceed creating the issue, please:
* visit **/admin/help**, and find the relevant module documentations.
* install the samples, if relevant:
[Slick example](https://www.drupal.org/project/slick_extras).
* ensure the library is loaded, not 404, by viewing it in a browser.
* cross-check against other versions of the library.
* switch to stock (Responsive) Bartik for just in case it is your custom theme.
* switch to default formatters, image to Image, text to Default, etc.
* use matching or similar branches or tags for related modules.
* check out dups at project issues, your problem may be already addressed.
* be kind with proper reproduction, enough details, screen shots of form, etc.
* specific to Slick alike, export the optionset, if relevant to this issue.
* consult descriptions on each form item.
* consult the provided TROUBLESHOOTING section on any of the modules.
* file it a support request, if unsure. We'll mark a bug a bug even if you
file it under support requests.
Hopefully resolved, before you create one.
If you see a persistent issue after reading/ addressing the above, go ahead!
