You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
136 lines
3.7 KiB
136 lines
3.7 KiB
2 months ago
|
# Kirby Image Crop Field
|
||
|
|
|
||
|
|
This plugin provides a field for cropping images visually and very flexibly.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
The field is based on [vue-cropperjs](https://github.com/Agontuk/vue-cropperjs
|
||
|
|
) and [gumlet/php-image-resize](https://github.com/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](https://getkirby.com/docs/reference/panel/blueprints/file).
|
||
|
|
Define an appropriate file blueprint for images and add the field as follow:
|
||
|
|
|
||
|
|
> `/site/blueprints/files/image.yml`:
|
||
|
|
> ```yaml
|
||
|
|
> 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](https://getkirby.com/docs/reference/plugins/extensions/file-methods) 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`:
|
||
|
|
> ```yaml
|
||
|
|
> 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](https://getkirby.com/docs/reference/plugins/extensions/file-methods) called `croppedImage` in order to work with the cropped image in templates and snippets:
|
||
|
|
|
||
|
|
> ```html
|
||
|
|
> <figure>
|
||
|
|
> <?= $page->image()->croppedImage() ?>
|
||
|
|
> </figure>
|
||
|
|
|
||
|
|
|
||
|
|
## Issues
|
||
|
|
|
||
|
|
Feel free to file an [issue](https://github.com/steirico/kirby-plugin-image-crop-field/issues) 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
|
||
|
|
|
||
|
|
## Credits
|
||
|
|
|
||
|
|
* [Rico Steiner](https://github.com/steirico)
|
||
|
|
* [vue-cropperjs](https://github.com/Agontuk/vue-cropperjs)
|
||
|
|
* [gumlet/php-image-resize](https://github.com/gumlet/php-image-resize)
|