Image Cropper Plugin

  • Authors: Antony Jones
0 vote
Dependency:
compile ":image-cropper:0.2.1"

 Documentation

Summary

Allows your users to visually crop images to their preferred size/ratio using an easy javascript interface with drag handles and preview

Installation

grails install-plugin image-cropper

Description

The Grails Image Cropper plugin is a Grails Tag Library which provides DEFusion's Javascript Image Cropper. It uses scriptaculous and prototype to crop an image from one size into another.

Note that the plugin does not physically change your image, only gives you the coordinates and dimensions of the user's crop so that you may do as you wish to the image, based on their crop. In a future version, a cropping service which can output an altered copy of the image will be provided.

Features

  • Cross Browser
  • Size Limitation
  • Ratio Limitation
  • Drag Handles to resize image in any direction
  • Full unit test coverage of both JavaScript and TagLib.
License
  • BSD Licensed - The source code contains a copy of the original distributed files, without modifications.
Basic Usage

To use the tag, simply place the following code into your GSP:

<cropper:crop imageId="your-image-id" />

'your-image-id' above should reference the 'id' attribute of an image tag. It is this image tag which will become croppable.

You will probably want to do something with the cropped image after your user has cropped it to their liking. You need to use the onEndCrop callback to do this. The following example outputs the coordinates and dimensions of the cropped image:

<img id="foo" src="foo.jpg" />
<cropper:crop imageId="foo" >
  <cropper:onEndCrop>
     $( 'x1' ).value = coords.x1;
     $( 'y1' ).value = coords.y1;
     $( 'x2' ).value = coords.x2;
     $( 'y2' ).value = coords.y2;
     $( 'width' ).value = dimensions.width;
     $( 'height' ).value = dimensions.height;
  </cropper:onEndCrop>
</cropper:crop>

The onEndCrop tag will sort out the callback format for you, so you will only need to implement the javascript to be used within your callback.

Callback format

There is only one callback, onEndCrop. It must be nested inside the crop tag. The variables of which are listed below:

EventTagCallback parameters you have access to
onEndCrop<cropper:onEndCrop> alert("coords: "+coords, "dimensions: "+dimensions); </cropper:onEndCrop>coords, dimensions

Advanced Configuration

There are a multitude of configuration options you can pass to the image cropping as attributes. These are well documented on the original library's page, but they are summarised them for you here:

Allowable attributes to the uploader tag

Attribute Name Description Allowed values
imageIdRequired: id of the image tag whose image you wish to crop.String
minWidthMinimum width of cropInteger
maxWidthMaximum width of cropInteger
minHeightMinimum height of cropInteger
maxHeightMaximum height of cropInteger
displayOnInitWhether to display the cropped area on initialisation (if specifying min/max width or ratio)'true', 'false' (+)
ratioDimDefine a restrictive ratio, JS Object with properties x and yJavaScript Object
captureKeysWhether to allow moving the select area with the arrow keys'true', 'false' (+)
onLoadCoordsCoordinates JS Object, containing properties x1, y1, x2, y2JavaScript Object