DEfusion.org.uk

Announcement: V2 plans & fund raising

Please take a moment to read my plans for version 2 of the cropper and how you can support it.

Details

About

The JavaScript image cropper UI allows the user to crop an image using an interface with the same features and styling as found in commercial image editing software, and is is based on the Prototype JavaScript framework and script.aculo.us.

Initially I performed quite a lot of searching for some ready made solutions to meet my requirements, but found none that had the complete feature set that I required or any complete versions based on Prototype.

So after a week and a half of work, I present the JavaScript image cropper UI, built on Prototype & script.aculo.us.

Features

• Un-obtrusive
• Based on Prototype and script.aculo.us
• Image editing package styling & functionality, the crop area functions and looks like those found in popular image editing software
• Dynamic inclusion of required styles
• Drag to draw areas
• Shift drag to draw/resize areas as squares
• Selection area can be moved
• Selection area can be resized using resize handles
• Allows dimension ratio limited crop areas
• Allows minimum dimension crop areas
• Allows maximum dimensions crop areas, if both min & max set as the same value then we'll get a fixed cropper size on the axes as appropriate and the resize handles will not be displayed as appropriate
• Allows dynamic preview of resultant crop (if minimum width & height are provided), this is implemented as a subclass so can be removed if not required
• Movement of selection area by arrow keys (shift + arrow key will move selection area by 10 pixels)
• All operations stay within bounds of image
• All functionality & display compatible with most popular browsers supported by Prototype, tested in:
  • PC: IE 6 & 5.5, Firefox 1.5, Opera 8.5 (see known issues) & 9.0b
  • MAC: Camino 1.0, Firefox 1.5, Safari 2.0

Usage

Extract to a directory of your choosing e.g. 'scripts/cropper/' and include the script and the required Prototype & script.aculo.us scripts:

Options

ratioDim obj

The pixel dimensions to apply as a restrictive ratio, with properties x & y.

minWidth int

The minimum width for the select area in pixels.

minHeight int

The mimimum height for the select area in pixels.

maxWidth int

The maximum width for the select areas in pixels (if both minWidth & maxWidth set to same the width of the cropper will be fixed)

maxHeight int

The maximum height for the select areas in pixels (if both minHeight & maxHeight set to same the height of the cropper will be fixed)

displayOnInit int

Whether to display the select area on initialisation, only used when providing minimum width & height or ratio.

onEndCrop func

The callback function to provide the crop details to on end of a crop.

captureKeys boolean

Whether to capture the keys for moving the select area, as these can cause some problems at the moment.

onloadCoords obj

A coordinates object with properties x1, y1, x2 & y2; for the coordinates of the select area to display onload

The callback function

The callback function is a function that allows you to capture the crop co-ordinates when the user finished a crop movement, it is passed two arguments:

• coords, obj, coordinates object with properties x1, y1, x2 & y2; for the coordinates of the select area.
• dimensions, obj, dimensions object with properities width & height; for the dimensions of the select area.

An example function which outputs the crop values to form fields:

Basic interface

This basic example will attach the cropper UI to the test image and return crop results to the provided callback function.

Minimum dimensions

You can apply minimum dimensions to a single axis or both, this example applies minimum dimensions to both axis.

Select area ratio

You can apply a ratio to the selection area, this example applies a 4:3 ratio to the select area.

With crop preview

You can display a dynamically produced preview of the resulting crop by using the ImgWithPreview subclass, a preview can only be displayed when we have a fixed size (set via minWidth & minHeight options). Note that the displayOnInit option is not required as this is the default behaviour when displaying a crop preview.

Known Issues

• Safari animated gifs, only one of each will animate, this seems to be a known Safari issue.
• After drawing an area and then clicking to start a new drag in IE 5.5 the rendered height appears as the last height until the user drags, this appears to be the related to another IE error (which has been fixed) where IE does not always redraw the select area properly.
• Lack of CSS opacity support in Opera before version 9 mean we disable those style rules, if Opera 8 support is important you & you want the overlay to work then you can use the Opera rules in the CSS to apply a black PNG with 50% alpha transparency to replicate the effect.
• Styling & borders on image, any CSS styling applied directly to the image itself (floats, borders, padding, margin, etc.) will cause problems with the cropper. The use of a wrapper element to apply these styles to is recommended.
• overflow: auto or overflow: scroll on parent will cause cropper to burst out of parent in IE and Opera when applied (maybe Mac browsers too) I'm not sure why yet.

Next Steps

Announcement: V2 plans & fund raising

Please take a moment to read my plans for version 2 of the cropper and how you can support it.

Comments

There have been 494 comments so far, join the discussion.

Pages: « 25 … 11 10 9 8 7 6 5 4 3 2 [1] Show All

myCropper = new Croper.Img( ...arguments... );

myCropper.setAreaCoords( { x1: 0, y1: 0, x2: 50, y2: 50 } );
myCropper.drawArea();