Requirements
Install
composer require wearebase/web-images, (*1)
If you want to install somewhere other than vendor, in your composer.json add the following:, (*2)
"extra": {
"installer-paths": {
"wp-content/themes/timber/packages/{$name}": ["wearebase/web-images"]
}
}
What's included
-
blazy, created by Bjørn Klinggaard with an MIT License.
-
Docs here.
- (These files are held in this repo for simplicity as bLazy is not available on Composer and pulling it from npm or Bower is an added dependency.)
- I have also included a copy of the documentation as it is held on a private website which may be unavailable.
- lazyLoad markup and scss to allow for full size backgrounds, images, and TimberImages
- background-size.min.htc to allow for backwards compatibility of
background-size: cover;
Usage
Enabling Views
First of all, you must add the views folder to your Twig template load path., (*3)
If you're not using Timber, then simply use lazyImages.twig as a universal Twig file., (*4)
Timber
Add the loadpath to your functions.php. You must re-add the default Theme view folder in here too as it may override the Timber view folder., (*5)
If you're using Timber, then use timberImages.twig., (*6)
Enabling Macros
In your layout file, or in individual macros or components:, (*7)
{% import 'lazyImages.twig' as base_image %}, (*8)
or if you're using Timber,, (*9)
{% import 'timberImages.twig' as base_image %}, (*10)
Enabling Sass
- Add the Sass to your build path. If you're using Compass, add this to your config.rb:
add_import_path "vendor/wearebase/web-images/scss"
-
@import "autoload". to get everything you need.
- In your project variables, you can optionally add the following to override default values:
-
$base-lazy-transition-speed (500ms)
Enabling JS
- Add the JS file(s) to your page.
Enabling background-size.
Background-size is now disabled by default. To use this, drop the background-size.min.htc file to your webroot., (*11)
You'll also need to add CSS rules to your background images in your own code to use it., (*12)
A reference to a htc file must be absolute., (*13)
LazyLoading
- Activate bLazy with
var bLazy = new Blazy(); on your page. Trigger it inside $(window).load() for the best results.
- Revalidate bLazy (on a resize, for example) with
bLazy.revalidate();.
- Use
b-lazy as a class on any div or img with a data-src to lazyLoad it. Preferably use the macros included in this package to enable the following:
- Lazy images, with optional support for retina
- Lazy TimberImages, with optional support for retina
- Lazy background, with optional support for retina
- All of the included functions supply a
<noscript> version for non-JS users.
Macros
{{ base_image.lazy(images, alt, classes, width, height) }}
Bog standard lazy img. Give it the following vars:, (*14)
- Array of 1x and 2x image URLs, OR a string of 1x image
- Alt: String to be used as the alt tag, optional (if empty, uses an empty alt tag, which forces Screen Readers to not read the image at all)
- Classes: Any additional classes as a string to add to the image, optional
- Width: Int, optional
- Height: Int, optional
There is also a standard 'img' macro if you need to switch a lazy image to a normal image tag., (*15)
{{ base_image.TimberImages(ids, alt, classes, sizes) }}
This is a preferable function if you know the ID of an image., (*16)
This is great for most scenarios, but a specific scenario might be that you have a 'banner' image size set up for your Wordpress images. You can then request the Featured Image of a post in the size 'banner'. Or if you're feeling fancy, add a 'banner-2x' and request ['banner', 'banner-2x'] to get a retina size of that banner., (*17)
Pass this the following vars:, (*18)
- id of image (recommended) OR an array of ids for when you want to use a different 2x image (not recommended)
- Alt: String to be used as the alt tag. Optional (if empty, uses the 'caption' of an image set in Wordpress)
- Classes: Any additional classes to add to the image as a string. Optional
- Sizes: string or array of string sizes. If empty, uses 'full'. Optional
{{ base_image.background(images, classes) }}
- Use the included background macro to easily create a full size lazyloaded background. By default these will fade in, but you can disable that by adding
b-no-fade class to backgrounds when triggering the macro.
- A parent of a full size background must be position:relative, or use the
bg-parent class.
Pass this the following vars:, (*19)
- URL String of image to use as a background
- Any additional classes you want to use, as a string
Wallogit.com
