adhocore / twig-yall
Lazy load image in twig using malchata/yall.js
Fund package maintenance!
adhocore
paypal.me/ji10
Installs: 3 539
Dependents: 0
Suggesters: 0
Security: 0
Stars: 12
Watchers: 2
Forks: 1
Open Issues: 1
Requires
- php: >=7.0.0
Requires (Dev)
- phpunit/phpunit: ^6.5 || ^7.5
- twig/twig: ^1.42 || ^2.12 || ^3.0
This package is auto-updated.
Last update: 2024-10-06 09:50:48 UTC
README
It is a twig extension around malchata/yall.js
for lazy loading img
, picture
, video
, iframe
etc.
(Also supports source
tag and srcset
attribute).
Eager loading of images and videos not only makes webpage slow and clumsy but also consumes a lot of bandwidth.
If you use twig templating system for your view layer, this extension defers loading of resources so they are loaded only when required in viewport.
Installation
composer require adhocore/twig-yall
Usage
First setup twig to register this extension:
// Use your loader of choice $twig = new Twig\Environment(new Twig\Loader\ArrayLoader); // Register Yall with defaults $twig->addExtension(new Ahc\TwigYall\Yall); // Configuring Yall instance: $twig->addExtension(new Ahc\TwigYall\Yall( 'polyfillJs' => '<custom url to polyfill>', 'yallJs' => '<custom url to yall.js>', 'lazyClass' => '<default lazy class>', 'placeholder' => '<default placeholder image url>', ));
Voila, then in twig templates you would either use {% lazyload %}
block to lazyload whole block at once
OR individually lazyload each resources with {{ lazify() }}
.
In both cases, you must call {{ yallify() }}
somewhere at the footer.
lazyload
With placeholder
config set to 'default.png'
, below template
<img src="apple.jpg" /> {# not lazyloaded #} {% lazyload %} <img src="ball.jpg" /> {# lazyloaded #} <img src="cat.jpg" class="no-lazy" /> {# not lazyloaded #} <img src="cat.jpg" data-src="..." /> {# not lazyloaded #} <video poster="vid.jpg"> {# lazyloaded #} <source src="vid1.mp4"> {# lazyloaded #} <source src="vid2.mp4"> {# lazyloaded #} </video> <video class='no-lazy' src="..."></video> {# not lazyloaded #} <picture><source src="pic.jpg"></picture> {# lazyloaded #} {% endlazyload %} <img src="..."> {# not lazyloaded #}
will be rendered as:
<img src="apple.jpg" /> <img class="lazy yall" src="default.png" data-src="ball.jpg" /> <img src="cat.jpg" class="no-lazy" /> <img src="cat.jpg" data-src="..." /> <video class="lazy yall" poster="default.png" data-poster="vid.jpg"> <source class="lazy yall" data-src="vid1.mp4"> <source class="lazy yall" data-src="vid2.mp4"> </video> <video class='no-lazy' src="..."></video> <picture><source class="lazy yall" data-src="pic.jpg"></picture> <img src="...">
lazify
only src
<img {{ lazify("/my/img.jpg") }} />
will be rendered as:
<img class="lazy yall" src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAI=" data-src="/my/img.jpg" />
See stackoverflow for the usage of data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAI=
.
with class
<img {{ lazify("logo.png", "cls1 cls2") }} />
will be rendered as:
<img class="cls1 cls2 lazy yall" src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAI=" data-src="logo.png" />
custom placeholder
<img {{ lazify("logo.png", "cls1 cls2", "/img/placeholder.png") }} />
will be rendered as:
<img class="cls1 cls2 lazy yall" src="/img/placeholder.png" data-src="logo.png" />
video poster
<video {{ lazify({poster: "video/poster.jpg"}, "video", "dummyposter.jpg") }}>
will be rendered as:
<video class="video lazy yall" poster="dummyposter.jpg" data-poster="video/poster.jpg">
source tag
<source {{ lazify({srcset: "img2x.jpg 2x, img1x.jpg 1x"}) }}>
will be rendered as:
<source class="lazy yall" data-srcset="img2x.jpg 2x, img1x.jpg 1x">
src+srcset
<img {{ lazify(["src.jpg", "src2x.jpg 2x", "src1x.jpg 1x"], "", "dummy.jpg") }} />
will be rendered as:
<img class="lazy yall" src="dummy.jpg" data-src="src.jpg" data-srcset="src2x.jpg 2x, src1x.jpg 1x" />
yallify
Important: Do not forget to put the yall loader somewhere in the footer twig template:
{{ yallify() }}
Which by default loads yall 3.1.7 with polyfills. You can set yall.js version, and turn off polyfill like so:
{{ yallify("3.1.6", "") }} {# load yall v3.1.6 but not polyfill #}
You can pass yall options in third param. For event callbacks wrap it in <raw></raw>
:
{{ yallify(null, null, {observeChanges: true, events: {load: "<raw>function(){}</raw>"}}) }}
will be rendered as:
<script src="https://polyfill.io/v2/polyfill.min.js?features=IntersectionObserver" async></script> <script src="https://unpkg.com/yall-js@3.1.7/dist/yall.min.js" async></script> <script type="text/javascript"> document.addEventListener("DOMContentLoaded", function() { window.setTimeout(function () { yall({ "observeChanges": true, "events": { "load": function(){} }, "lazyClass": "lazy" }); }, 99); }); </script>
PS:
The inputs sent to lazify()
or yallify()
are not validated by this library.
From malchata/yall.js
:
Use appropriate width and height attributes, styles, and lightweight placeholders for your images.
Contributing
Please check the guide
LICENSE
© MIT | 2019, Jitendra Adhikari