README

Do you need to crop your images for art direction purposes?

Perhaps this is for responsive design, or perhaps you're tired of CroppedResize, PaddedResize, Square and general centre-based resizing functionality in SilverStripe that doesn't quite meet your image cropping needs.

Maybe CropperField is for you. Whilst it's called CropperField, that's just the user interface. Behind the scenes, a clean and extensible architecture allows you to crop almost anything - external URLs, documents, video frames, etc..

For the field itself, the frontend is powered by Cropper v0.7.5 by Fengyuan Chen.

Warning: Under development / alpha. Do not use unless you are prepared to contribute!

Installation

1. composer require willmorgan/silverstripe-cropperfield
2. Specify a version constraint.

• While this module is in heavy development, you probably want to use ~0.X or similar.

Screenshot

The field currently looks like this in a CMS setting.

Usage

1. Specify a $has_one Image relationship on the object that should own the cropped image.
2. Specify an image based UploadField whose image you wish to crop.

• Only UploadField is supported right now. Non-images will break. Sorry.

1. Create an AdapterInterface implementor to pass into your CropperField

• See [1]; the adapters are generic enough for you to supply anything - as long as there's a File object backing it (regardless of whether it exists).

1. Set some options, if you so desire.
2. Happy cropping.

Example

In this example, a configuration like this has been set up:

$has_one = array(
	'MyBigPhoto' => 'Image',
	'MyArtDirectionCrop' => 'Image',
);

Inside a getCMSFields call, or similar:

$uploadField = new UploadField('MyBigPhoto', 'Big Photo Uploader');
$cropperField = new CropperField\CropperField(
	'MyArtDirectionCrop',
	'Cropped Image',
	new CropperField\Adapter\UploadField(
		$uploadField
	)
);

You can now use $MyArtDirectionCrop in your template as you would any other image (i.e. you can use $ResizeRatio, $Square, etc.)

The initial benefit is the CMS user gets to specify the true focus point of a potentially high resolution image, and you / your frontend team can reuse that base cropped image responsively, be it using srcset, picture + source, etc.

Options

You can set these options on the CropperField to get some control over your CMS users' actions.

Supplied Adapters

• CropperField\Adapter\UploadField for image based upload fields

Supplied Croppers

• CropperField\Cropper\GD for GD installations
• Imagick coming soon

Customisation

• Templates: you can easily customise the template used - just override CropperField.ss
• You can write your own croppers (say, for Imagick).
  1. Implement the CropperInterface
  2. Either set it on a per-instance basis using CropperField->setCropper()
  3. Set it in YML, overriding CropperFactory.cropper. The factory uses Injector for DI.

Compatibility

• While Cropper is able to support browsers as old as IE8, the CropperField CMS UI has been tested only in Chrome.

Similar modules

If this doesn't look right for you*, check out some alternatives:

• @jonom has built silverstripe-focuspoint, which is powered by his popular jQuery FocusPoint library

* As a sidenote, I'd appreciate you taking the time to let me know why

Licensing

• SilverStripe CropperField is released under the BSD License; however, please note:
• Cropper v0.7.5 is released under the MIT license.

Built by

Will Morgan, who is available for hire.