README

This plugin provides a field for cropping images visually and very flexibly.

The field is based on vue-cropperjs and gumlet/php-image-resize.

Installation

Use one of the alternatives below.

Download

Download and copy this repository to `/site/plugins/kirby-plugin-image-crop-field.

Git submodule

git submodule add https://github.com/steirico/kirby-plugin-image-crop-field.git site/plugins/kirby-plugin-image-crop-field

Composer

composer require steirico/kirby-plugin-image-crop-field

Usage

File Blueprint Usage

The plugin defines the new field type imagecrop which can be used in file blueprints. Define an appropriate file blueprint for images and add the field as follow:

/site/blueprints/files/image.yml:

fields:
  crop:
    label: Image Crop
    type: imagecrop
    minSize:
      width: 700
      height: 250
    targetSize:
      width: 1400
      height: 500
    preserveAspectRatio: true

Blueprint Options

`minSize`

Defines the minimum allowed size of the area that can be cropped from the original image.

width: Minimum allowed width, bigger or equal to 1
height: Minimum allowed height, bigger or equal to 1

Defaults:

width: 1
height: 1

`targetSize`

Target size of the image after it has been cropped. The resulting image will be scaled to width as defined by targetSize.width and height as defined by targetSize.height.

width: Width of the target image, bigger or equal to 1
height: Minimum allowed height, bigger or equal to 1

For both, width and height, negative values are interpreted as absolute values.

Defaults: The resulting image represents the cropped area and is not scaled.

`preserveAspectRatio`

Whether to preserve the aspect ratio of the crop area as defined by minSize.width / minSize.height or to allow free cropping:

true: Preserve aspect ratio
false: Free cropping

Default: false

Cropped Image in the Panel

The plugin provides the file method called croppedImage. Applied as any other file method, croppedImage provides a file object of the cropped version of origin image.

The following configuration previews the cropped image in a files sections:

/site/blueprints/pages/album.yml:

title: Album

sections:
  images:
    type: files
    layout: cards
    template: image
    info: "{{ file.dimensions }}"
    image:
      ratio: 16/9
      cover: false
      query: file.croppedImage
    min: 1
    size: small

Use Cropped Image in Templates and Snippets

Use the the file method called croppedImage in order to work with the cropped image in templates and snippets:

<figure>
  <?= $page->image()->croppedImage() ?>
</figure>

Issues

Feel free to file an issue if you encounter any problems or unexpected behavior.

Currently there is a know issue that crooped images apear twice when geting images by $page->images().

License

MIT

steirico / kirby-plugin-image-crop-field

Maintainers

Details