zz
/
v1
forked from a64f7bb4-7358-4778-9fbe-3b882c34cc1d/v1
2
0
Fork 0
Code Pull Requests Activity
v1/web/modules/contrib/blazy/docs/TROUBLESHOOTING.md

11 KiB
Raw Blame History

TROUBLESHOOTING

  • Any javascript-related issues might no longer be valid when No JavaScript lazy enabled. Unless the exceptions, things that Native doesn't support (Blur, BG, Video, etc.) are met, or for those who still support old IEs, and cannot ditch lazyloader script, yet.

  • Switch to core Bartik for a mo, in case your custom theme is the culprit.

  • 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. The main reason: When being resized, the browser gave no data about pixel ratio from desktop to mobile, not vice versa. Unless delayed for 4s+, not less, which is of course unacceptable.

  • 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.

  • Be sure to view browser console as anonymous, not only as admin users.

  • 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

1. JavaScript Errors

Any references to bLazy library is no longer required for forked version at 2.6.
Symptons:
Blazy is not defined. Images are gone, only eternal blue loader is flipping like a drunk butterfly.

Solution:
Ensure that no extras errors. Steps:

  • Switch to core Bartik for a moment in case your theme is the culprit. Any theme JS errors might break Blazy. Press F12 at browsers to fix them one by one.
  • Try disabling Disconnect option under IO.

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.

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.

5. BLAZY FILTER

Blazy Filter must run after Align/ Caption filters as otherwise the required CSS class b-lazy will be moved into <figure> 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.

Blazy Filter is useless and broken when you enable Media embed or Display embedded entities. You can disable Blazy Filter in favor of Blazy formatter embedded inside Media embed or Display embedded entities instead. However it might be useful for User Generated Contents (UGC) where Entity/Media Embed are likely more for privileged users, editors, admins, alike. Or when Entity/Media Embed is disabled.

6. INTERSECTION OBSERVER API

This API will not be used if No JavaScript lazy option enabled unless the exceptions, things that Native doesn't support (Blur, BG, Video, etc.) are met.

  • 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.

FYI: IO is also used for infinite pager and lazyloaded blocks like seen at IO.module.

7. BLUR IMAGE EFFECT

/admin/config/media/blazy

The Image effect Blur will override Placeholder option. Will use Thumbnail style option at Blazy formatters for the placeholder with fallback to core Thumbnail image style.

For best results:

  • Choose Aspect ratio option, non-fluid is better;
  • Use similar aspect ratio for both Thumbnail style and Image style;
  • Adjust Offset and or threshold;
  • The smaller the better.

Use hook_blazy_image_effects_alter() to add more effects -- curtain, fractal, slice, whatever.

Limitations: Currently only works with a proper Aspect ratio as otherwise collapsed image. Be sure to add one. If not, add regular CSS width: 100% to the blurred image if doable with your design.

8. ASPECT RATIO

UPDATE 05/02/2020: Blazy RC7+ is 99% integrated with Responsive image, including CSS background and the notorious aspect ratio Fluid. The remaining 1% is some unknown glicthes.

Aspect ratio was never supported for Responsive image till Blazy 2.rc7+, not fully though. One remaining issue is to make Aspect ratio Fluid work for: CSS background + Picture element.

Any fixed Aspect ratio (4:3, 16:9, etc) should immediately work as long as you understand what it means.

Aspect ratio Fluid worked with custom breakpoints (deprecated), not Responsive image, yet. If you want Aspect ratio for Responsive image, choose anything but Fluid.

Any fixed Aspect ratio (4:3, 16:9, etc), but Fluid, wants consistent aspect ratio down to mobile, which means it won't work with art direction technique, or Picture element. Check out few aspect ratio samples

Temporary workaround is to add regular CSS width: 100% to the controlling image if doable with your design. And a min-height per breakpoint via CSS mediaqueries.

Aspect ratio fixes many issues with lazyloaded element -- collapsed, distorted, excessive height, layout reflow, etc., including making iframe fully responsive. However it doesn't fix everything. Please bear with it.

If you have display issues, the correct Aspect ratio is your first best bet.

Depending on your particular issue, enable or disable, either way, is your potential solution. One good sample when Aspect ratio makes no sense is GridStack gapless grids. Image sizes, hence Aspect ratio, cannot be applied to gapless grids. Aspect ratio is based on image sizes, not grid sizes.

9. BLAZY WITHIN SCROLLING CONTAINER DOES NOT LOAD

/admin/config/media/blazy

Note: IO does not need it, old bLazy does.

If you put Blazy within a scrolling container, provide valid comma separated CSS selectors, except #drupal-modal, .is-b-scroll, e.g.: #my-scrolling-container, .another-scrolling-container.

A known scrolling container is #drupal-modal like seen at Media library. A scrolling modal with an iframe like Entity Browser has no issue since the scrolling container is the entire DOM. Must know .blazy parent container which has CSS rules containing overflow with values anything but hidden such as auto or scroll. Press F12 at any browser to inspect elements.

Default to known #drupal-modal, .is-b-scroll. The .is-b-scroll can be used when Blazy UI is unreachable without extra legs.

10. LINKED FIELD INTEGRATION

Under Media switcher option, only Image to iFrame makes sense. The rest like Image to lightboxes, or Image linked to content will obviously be ignored since these will output A tag just like what Linked Field does. Alternatively leave Media switcher empty, if no videos are mixed with images. With Image to iFrame, the good thing is video will be still playable, and the image be linked as required. Best of Both Worlds for real.

11. VIEWS GOTCHAS

Blazy provides a simple Views field for File Entity, and Media. Also a Blazy Grid views style plugin.

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.

12. NATIVE GRID MASONRY

Q: The native grid masonry (Display style: native Grid, Grid large: any single number) doesn't have correct bottom gaps?
A: It does. Your eyes are likely being tricked. Solutions:

  • Try adding background color to .grid__content. Notice even gaps. The problem is inner divities do not have 100%. Read more below.
  • If image and applicable, enable CSS background using Blazy formatter. If using Views, remove extra useless DIVs under Style settings by setting them all to None and keep them with caution. And uncheck Provide default field wrapper elements under Show: Fields Settings. So that Blazy CSS background fills in the gaps. Try Aspect ratio: Fluid to minimize reflow in case useful here.
  • If not or still an issue, manually adjust the image and the inner DIVs of .grid__content heights to 100%.
  • For text contents, having light background color is enough.
  • Add enough min-height per breakpoint to the grid root container. See and override blazy.nativegrid.css to better suit your site needs.
  • If you don't want all these headaches, consider a more robust GridStack. It may take care these types of issues for you.

13. BLAZY IMAGES DO NOT LOAD

Images does not load within hidden tabs, or other hidden containers:

  • /admin/config/media/blazy
  • Enable Load invisible option.

Only an issue with old bLazy, not IO, AFAIK. Other than that, be sure to read back the topmost troubleshooting section.

14. 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:

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.

Check out Update SOP for the non-drush users.