Download the PHP package croustille/twill-image without Composer
On this page you can find all versions of the php package croustille/twill-image. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package twill-image
Twill Image
Twill Image is a package designed to work with Twill to display responsive images easily on your site. It leverages Twill's image processing capabilities and adds modern lazy-loading techniques. It supports responsive images, art direction and fixed width images.
<picture>
with multiple<source>
elements- Twill's low-quality placeholder (LQIP)
- Art direction (multiple crops)
- WebP and JPEG support
- Native lazy loading with
loading='lazy'
- Support custom CSS classes to use with Tailwind CSS
Contents
- Installation
- Configuration file
- Usage
- The
Image
model - Available methods
crop
width
height
sources
sizes
columns
srcSetWidths
preset
render
toArray
- The facade
render
method - List of arguments
- Examples
- The
- Configuration
- Presets
- List of options
- Frontend breakpoints and grid structure
columns
examplecolumns
presetcolumns
outputcolumns
custom class
- Art directed images
- Multiple medias
Installation
Install the package to your existing Twill project with Composer.
Configuration file
The configuration file contains a few general settings and this is where you can define preset for your images.
Publish config/twill-image.php
to your app's config folder.
Usage
The Image
model
The Image
model allows you to interact fluently with a media object.
Argument | Type | Default | Description |
---|---|---|---|
$object (Required) |
A17\Twill\Models\Media A17\Twill\Models\Block object |
Your Twill module or block object | |
$role (Required) |
string |
Media role |
|
$media |
A17\Twill\Models\Media |
null |
Media instance |
Available methods
Once you have created an instance of the Image
model, you can interact by using one or chaining many of these methods.
crop
You can specify the crop name by passing it as an argument. By default, the Image
model will look for a crop name default
and if it isn't availble, it will look for a single crop and select it. If it can't determine the crop, it will result in an error.
width
To set the width of the image, you can use this method. The default is an image of 1000 pixels wide. This is useful if you need to display an image with a fixed width or if you know in advance that you will a larger image than the default.
Note: the width is applied to the "fallback" image (<img src="{{ $image }}">
) and to determine the number of image URLs to add to the srcset
attribute.
height
You can set the height of the image with this method. Similar to the width
method above, it is most useful for fixed-size image. When not used, the height is determined by the aspect ratio of the image and inferred from the width.
sources
To use mutliples <source>
elements, you can pass a array to this method by listing the sources other than the main crop. Each item in the array must have a mediaQuery
and a crop
key in order to generate the proper srcset
. You can pass an optional width and height. This is useful when used with the crop
method to set the main image crop. See also Art directed images.
Media queries can also be generated from a frontend breakpoints and grid structure file by passing a columns
key instead of mediaQuery
. You can see the format below.
sizes
Use this method to pass a sizes
attribute to the model.
columns
As an alternative to the sizes
method, Twill Image provides a way to generate the sizes
attribute based on a frontend breakpoints and grid structure file. When placing this JSON file at the base folder of your app, the sizes
attribute can be generated from passing a series of breakpoints and columns number to this method.
This would tell how many columns the image will take at each breakpoint in order to generate to proper sizes
attribute.
Note: this method will have an effect only when frontend.config.json
exists at in base folder of your app.
srcSetWidths
Use this method to give a list a widths to generate the srcset
attribute. Without this method, Twill Image will auto generate a series of widths based on the image width.
preset
With this method you can use an object to pass a value to any of the above methods. You can also add a preset key to the config config/twill-image.php
and pass the name to this method.
You can directly pass the full object if you prefer.
render
This method will return the rendered view.
toArray
If you need to split the image generation from the render (exposing the Image
model data through a REST API for example), use this method to get all attributes as an array.
And use the render
method from the facade to render the view.
The facade render
method
As seen in the previous section, the image element rendering can be separated from the image attributes generation. You can use the Image
model to set up your image and pass the resulting object (or its array
format to the render
method to output the view).
or
List of arguments
Argument | Type | Default | Description |
---|---|---|---|
class |
string |
Add class(es) to the wrapper element | |
imageClass |
string |
Add class(es) to the img element | |
height |
int |
||
imageSizer |
boolean |
'auto' | Render the image sizer markup if true , if set to 'auto', the sizer is rendered when LQIP is set to true |
loading |
"lazy" \| "eager" |
lazy |
Set native lazy loading attribute |
lqip |
boolean |
See config | Use LQIP |
sizes |
string |
The image sizes attributes | |
imageStyles |
array |
[] |
Apply styles to placeholder and main img tags (ex.: [['object-fit' => 'contain']] |
Examples
Configuration
In config/twill-image.php
, you can define general options and image presets. A preset informs the Image::preset
method which crop to output along other options like responsive sources.
Presets
See above section about the preset
method.
List of options
Argument | Type | Default | Description |
---|---|---|---|
lqip |
boolean |
true |
Uses Twill LQIP method to generate responsive placeholder |
image_sizer |
boolean\|'auto' |
auto |
Output the sizer element. If left to auto, it will render the sizer if LQIP is set to true |
inline_styles |
boolean |
true |
Output default inline styles |
custom_classes |
object['main'\|'wrapper'\|'placeholder'] |
If inline styles are off, custom classes will be used instead allowing use with Tailwind CSS | |
webp_support |
boolean |
true |
If set to false , the type attribute is omitted from <source> elements |
presets |
object |
Art directed images
To use different crops with media queries, you need to list the other sources in a Image::preset
or by passing them to the Image::sources
method. The rendered image element with have only the ratio of the main crop and other ratio need to be added with CSS.
Let's say this is your preset art_directed
in your config:
It will output the image element with the class applied to the container.
Define styles for each breakpoint.
Frontend breakpoints and grid structure
We provide a way to generate sizes
and media
attributes by describing the structure of your page in a JSON file frontend.config.json
placed at the base of your app. An example is provided frontend.config.json.example
.
This file describes the breakpoints, main container widths, number of columns per breakpoints and inner/outer gutters. When this file exists in your project, you can use the columns
method on the Image
model or the columns
key in your preset and sources objects in order to generate dynamically the sizes
and media
attributes.
columns
example
This example assumes that you have the provided frontend.config.json
in your app's base_path
.
columns
preset
columns
output
The image source and fallback would have these sizes
and media
attributes (the elements have been simplified for clarity):
columns
custom class
You can provide your own custom class to be used instead of the one provided. You can create your own service and provide the class name in the config file:
The service must implement the interface A17\Twill\Image\Services\Interfaces\ImageColumns
.
This can also be useful if you simply need to override some of the proprties that are defined in the provided services.
Multiple medias
This is an example when you have multiple medias attached to a single role
.
All versions of twill-image with dependencies
area17/twill Version 2.*|3.*
laravel/framework Version ~5.6|~5.7|~5.8|^6.0|^7.0|^8.0|^9.0|^10.0|^11.0
spatie/laravel-view-models Version ^1.3