Kirby 3: Image Clip
Visual image clipping / cropping.
Overview
- Installation
- Requirements
- Consider a donation
- Panel Usage
- Replace Files Field
- Frontend Usage
- License
Installation
Download
Download and copy this repository to /site/plugins/k3-image-clip
Git submodule
git submodule add https://github.com/mullema/k3-image-clip.git site/plugins/k3-image-clip
Composer
composer require mullema/k3-image-clip
Requirements
- Kirby 3.6 -> use v3
- Kirby 3.5 -> use v2.2.0
- Kirby 3.3 -> use v2.1.0
- Kirby 3.2.5 -> use v2.0.0
- GD Library or ImageMagick
Consider a donation
This plugin is free but if you use it in a commercial project please consider to make a donation.
Panel Usage
This plugin comes with a image-clip
field. It is based on the files
field and supports all it's options. Read more about the files
field in the Kirby3 Docs.
Example blueprint:
myimages:
type: image-clip
query: site.find('photography/animals').images
layout: cards
size: small
clip:
minwidth: 400
minheight: 300
maxwidth: 800
maxheight: 600
ratio: fixed
- All values are in Pixels.
minwidth
,minheight
,maxwidth
,maxheight
limit the clip/crop select area.- None of the clip options are required, but in most cases it is recommended to define
minwidth
andminheight
. - Often it makes more sense to resize the resulting image than defining
maxwidth
andmaxheight
. ratio: fixed
locks the ratio- if
minwidth
andminheight
are defined, - or
maxwidth
andmaxheight
are defined, - or all of the above.
- if
The field does basic checks of image size and type but counts mainly on you defining e.g, accepted mime types or image sizes in a File Blueprint. You can filter the images list by template like that:
query: site.find('photography').children.images.filterBy('template', 'cover')
Replace Files Field
The image-clip
field is able to replace a files
field by changing the field type. Simply replace
type: files
with
type: image-clip
This works also vice versa to use the native files
field instead of the image-clip
field.
Frontend Usage
How to fetch the images defined in a image-clip
field.
Read about the clip()
method a bit further down.
Single Image
if ($image = $page->myimages()->toImage()) {
echo $image->clip(500);
}
- Important:
toFiledoes not work, usetoImage()
instead. toImage()
returns a File Object with all it's functions.
Multiple Images
foreach($page->myimages()->toImages() as $image) {
echo $image->clip(500);
}
- Important:
toFilesdoes not work, usetoImages()
instead. toImages()
returns a Files Collection with all it's functions.
File Methods
$file->clip()
Clip and resize. Generates a Thumbnail of the clip area.
Adapter for $file->thumb()
. Returns a FileVersion|File Object.
if ($image = $page->myimages()->toImage()) {
echo $image->clip(500);
}
$file->clip(200, 300); // bestfit
$file->clip(200); // width 200px
$file->clip(null, 300); // height 300px
$file->clip(); // clip area without resizing
- Used in combination with the
image-clip
Field, invokes automatically field clip data. - Arguments:
clip(width, height)
- if
width
andheight
are both defined, the image will be resized withbestfit
- if
$file->srcset()
Use this method to generate the srcset attribute for responsive images. Read more about it's functionality in the Kirby3 Docs
<?php if ($image = $page->myimages()->toImage()): ?>
<img srcset="<?= $image->srcset([300, 800, 1024]) ?>">
<?php endif; ?>
$file->thumb()
The thumb method accepts now the option clip
and can be used with any resizable image.
$file->thumb([
'width' => 400,
'clip' => [
'width' => 500,
'height' => 200,
'top' => 10,
'left' => 200
]
]);
- Clips/crops a square of 500x200px, 10px from top and 200px from the left end of the original image.
- Resizes the resulting image to 400px width.
- If
clip
andcrop
are used at the same time,crop
will be ignored.
Read more about the thumb
method in the Kirby3 Docs
$file->getClip()
Returns the clip data.
Can be useful e.g with the $file->thumb()
method.
if ($image = $page->myimages()->toImage()) {
echo $image->thumb([
'width' => 1200,
'grayscale' => true,
'clip' => $image->getClip()
]);
}
License
MIT