www.aleph1.co.uk Git - yaffs-website/blob - web/modules/contrib/blazy/README.txt

   1
   2 ABOUT
   3 Provides integration with bLazy to lazy load and multi-serve images to save
   4 bandwidth and server requests. The user will have faster load times and save
   5 data usage if they don't browse the whole page.
   6
   7
   8 FEATURES
   9 o Supports core Image.
  10 o Supports core Responsive image.
  11 o Supports Colorbox/Photobox, also multimedia lightboxes.
  12 o Supports Retina display.
  13 o Multi-serving images for configurable XS, SM and MD breakpoints, almost
  14   similar to core Responsive image, only less complex.
  15 o CSS background lazyloading, see Mason, GridStack, and Slick carousel.
  16 o IFRAME urls via via custom coded, Blazy Image with Media entity via Video
  17   Embed Media, or see Slick Video, Slick Media.
  18 o Delay loading for below-fold images until 100px (configurable) before they are
  19   visible at viewport.
  20 o A simple effortless CSS loading indicator.
  21 o It doesn't take over all images, so it can be enabled as needed via Blazy
  22   formatter, or its supporting modules.
  23
  24
  25 OPTIONAL FEATURES
  26 o Views fields for File ER and Media Entity integration.
  27 o Views style plugin Blazy Grid.
  28 o Field formatters: Blazy, and Blazy Image with Media integration.
  29
  30
  31 REQUIREMENTS
  32 - bLazy library:
  33   o Download bLazy from https://github.com/dinbror/blazy
  34   o Extract it as is, rename "blazy-master" to "blazy", so the assets are at:
  35
  36     /libraries/blazy/blazy.min.js
  37
  38
  39 INSTALLATION
  40 Install the module as usual, more info can be found on:
  41 http://drupal.org/documentation/install/modules-themes/modules-7
  42
  43
  44 USAGES
  45 Be sure to enable Blazy UI which can be uninstalled at production later.
  46 o Go to Manage display page, e.g.:
  47   admin/structure/types/manage/page/display
  48
  49 o Find "Blazy" formatter under "Manage display".
  50
  51 o Go to "admin/config/media/blazy" to manage few global options, including
  52   enabling support for lazyloading core Responsive image.
  53
  54 For custom usages, add a class "b-lazy" along with a "data-src" attribute
  55 referring to an expected image or iframe URL, or to any supported element:
  56 IMG, IFRAME or DIV/BODY, etc.
  57 Non-media element, DIV/BODY/etc., will have background image lazyloaded instead.
  58
  59 Wrap the parent container with [data-blazy attribute containing the expected
  60 options to limit the scope, or for simple need without aspect ratio. Add extra
  61 class .blazy to support aspect ratio with multi-serving images.
  62 And load the blazy library accordingly.
  63
  64
  65 MODULES THAT INTEGRATE WITH OR REQUIRE BLAZY
  66 o Blazy PhotoSwipe
  67 o GridStack
  68 o Intense
  69 o Mason
  70 o Slick (D8 only by now)
  71 o Slick Views (D8 only by now)
  72 o Slick Media
  73 o Slick Video
  74 o Slick Browser
  75
  76 Most duplication efforts from the above modules will be merged into
  77 \Drupal\blazy\Dejavu namespace.
  78
  79
  80 SIMILAR MODULES
  81 https://www.drupal.org/project/lazyload
  82 https://www.drupal.org/project/lazyloader
  83
  84
  85 TROUBLESHOOTING
  86 Resizing is not supported. Just reload the page.
  87
  88 VIEWS INTEGRATION
  89 Blazy provides two simple Views fields for File ER, and Media Entity.
  90
  91 When using Blazy formatter within Views, check "Use field template" under
  92   "Style settings", if trouble with Blazy Formatter as stand alone Views output.
  93   On the contrary, uncheck "Use field template", when Blazy formatter
  94   is embedded inside another module such as GridStack so to pass the renderable
  95   array accordingly.
  96   This is a Views common gotcha with field formatter, so be aware of it.
  97   This confusion should be solved later when Blazy formatter is aware of Views.
  98
  99 MIN-WIDTH
 100 If the images appear to be shrinked within a floating container, add
 101   some expected width or min-width to the parent container via CSS accordingly.
 102   Non-floating image parent containers aren't affected.
 103
 104 MIN-HEIGHT
 105 Add a min-height CSS to individual element to avoid layout reflow if not using
 106   Aspect ratio or when Aspect ratio is not supported such as with Responsive
 107   image. Otherwise some collapsed images containers will defeat the purpose of
 108   lazyloading. When using CSS background, the container may also be collapsed.
 109   Both layout reflow and lazyloading delay issues are actually taken care of
 110   if Aspect ratio is enabled in the first place.
 111
 112 Adjust, and override blazy CSS files accordingly.
 113
 114
 115 ROADMAP/TODO
 116 [x] Adds a basic configuration to load the library, probably an image formatter.
 117     2/24/2016
 118 [x] Media entity image/video, and Video embed field lazyloading, if any.
 119     10/25/2016
 120     Added both simple Blazy Media formatter and Views field Media Entity.
 121 o Makes a solid lazyloading solution for IMG, DIV, IFRAME tags.
 122
 123
 124 CURRENT DEVELOPMENT STATUS
 125 A full release should be reasonable after proper feedbacks from the community,
 126 some code cleanup, and optimization where needed. Patches are very much welcome.
 127
 128 Alpha and Beta releases are for developers only. Be aware of possible breakage.
 129
 130
 131 UPDATE SOP:
 132 Visit any of the following URLs when updating Blazy, or its related modules.
 133
 134 1. /admin/config/development/performance
 135   Unless an update is required, clearing cache should fix most issues.
 136
 137   o Hit "Clear all caches" button once the new Blazy in place.
 138   o Regenerate CSS and JS as the latest fixes may contain changes to the assets.
 139
 140 2. /admin/reports/status
 141   Check for any pending update, and run /update.php from the brower address bar.
 142
 143 3. If Twig templates are customized, compare against the latest.
 144
 145
 146 PERFORMANCE TIPS:
 147 o If breakpoints provided with tons of images, using image styles with ANY crop
 148   is recommended to avoid image dimension calculation with individual images.
 149   The image dimensions will be set once, and inherited by all images as long as
 150   they contain word crop. If using scaled image styles, regular calculation
 151   applies.
 152
 153
 154 AUTHOR/MAINTAINER/CREDITS
 155 gausarts
 156
 157 Contributors:
 158 https://www.drupal.org/node/2663268/committers
 159
 160
 161 READ MORE
 162 See the project page on drupal.org: http://drupal.org/project/blazy.
 163
 164 See the bLazy docs at:
 165 o https://github.com/dinbror/blazy
 166 o http://dinbror.dk/blazy/