willmorgan/silverstripe-cropperfield

Provides an interface for you to generate thumbnails of things in the CMS. Adapters can be used to extend the functionality to thumbnail videos, PDF documents, etc.

SilverStripe CropperField

, _(*1)

Do you need to crop your images for art direction purposes?, _(*2)

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., _(*3)

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.., _(*4)

For the field itself, the frontend is powered by Cropper v0.7.5 by Fengyuan Chen., _(*5)

Warning: Under development / alpha. Do not use unless you are prepared to contribute!, _(*6)

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., _(*7)

, _(*8)

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.
3. 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).
4. Set some options, if you so desire.
5. Happy cropping.

Example

In this example, a configuration like this has been set up:, _(*9)

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

Inside a getCMSFields call, or similar:, _(*10)

$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.), _(*11)

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., _(*12)

Options

You can set these options on the CropperField to get some control over your CMS users' actions., _(*13)

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:, _(*14)

• @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, _(*15)

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., _(*16)