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