Skip to content

Latest commit

 

History

History
183 lines (150 loc) · 5.19 KB

README.md

File metadata and controls

183 lines (150 loc) · 5.19 KB
Raw

Kirby 3: Image Clip

Visual image clipping / cropping.

Image Clip

Overview

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 and minheight.
  • Often it makes more sense to resize the resulting image than defining maxwidth and maxheight.
  • ratio: fixed locks the ratio
    • if minwidth and minheight are defined,
    • or maxwidth and maxheight are defined,
    • or all of the above.

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: toFile does not work, use toImage() instead.
  • toImage() returns a File Object with all it's functions.

Multiple Images

foreach($page->myimages()->toImages() as $image) {
    echo $image->clip(500);
}
  • Important: toFiles does not work, use toImages() 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 and height are both defined, the image will be resized with bestfit

$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 and crop 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

Credits