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.

Click here to lend your support to: JavaScript Image Cropper V2 fund raising and make a donation at www.pledgie.com !

Details

Version 1.2.0
Last updated 30th October 2006
Requirements
Demo View demo page
Links
License BSD License
Changelog
1.2.0
  • Added id to the preview image element using 'imgCrop_[originalImageID]'
  • #00001 - Fixed bug: Doesn't account for scroll offsets
  • #00009 - Fixed bug: Placing the cropper inside differently positioned elements causes incorrect co-ordinates and display
  • #00013 - Fixed bug: I-bar cursor appears on drag plane
  • #00014 - Fixed bug: If ID for image tag is not found in document script throws error
  • Fixed bug with drag start co-ordinates if wrapper element has moved in browser (e.g. dragged to a new position)
  • Fixed bug with drag start co-ordinates if image contained in a wrapper with scrolling - this may be buggy if image has other ancestors with scrolling applied (except the body)
  • #00015 - Fixed bug: When cropper removed and then reapplied onEndCrop callback gets called multiple times, solution suggestion from Bill Smith
  • Various speed increases & code cleanup which meant improved performance in Mac - which allowed removal of different overlay methods for IE and all other browsers, which led to a fix for:
  • #00010 - Fixed bug: Select area doesn't adhere to image size when image resized using img attributes
  • #00006 - Removed default behaviour of automatically setting a ratio when both min width & height passed, the ratioDimensions must be passed in
  • #00005 - Added ability to set maximum crop dimensions, 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
  • Switched keydown for keypress for moving select area with cursor keys (makes for nicer action) - doesn't appear to work in Safari
1.1.3
  • Fixed wrong cursor on western handle in CSS
  • #00008 & #00003 - Added feature: Allow to set dimensions & position for cropper on load
  • #00002 - Fixed bug: Pressing 'remove cropper' twice removes image in IE
1.1.2
  • Fixed bugs with ratios when GCD is low (patch submitted by Andy Skelton)
1.1.1
  • Fixed bug with rendering issues fix in IE 5.5
  • Fixed bug with endCrop callback issues once cropper had been removed & reset in IE
1.1.0
  • Fixed bug with IE constantly trying to reload select area background image
  • Applied more robust fix to Safari & IE rendering issues
  • Added method to reset parameters - useful for when dynamically changing img the cropper is attached to
  • Added method to remove cropper from image
1.0.0
  • Initial verison

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

Screen shot of cropper in action

  • 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:

HTML:
  1. <script type="text/javascript" src="scripts/cropper/lib/prototype.js" language="javascript"></script>
  2. <script type="text/javascript" src="scripts/cropper/lib/scriptaculous.js?load=builder,dragdrop" language="javascript"></script>
  3. <script type="text/javascript" src="scripts/cropper/cropper.js" language="javascript"></script>

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:

JavaScript:
  1. function onEndCrop( coords, dimensions ) {
  2.     $( 'x1' ).value = coords.x1;
  3.     $( 'y1' ).value = coords.y1;
  4.     $( 'x2' ).value = coords.x2;
  5.     $( 'y2' ).value = coords.y2;
  6.     $( 'width' ).value = dimensions.width;
  7.     $( 'height' ).value = dimensions.height;
  8. }

Basic interface

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

HTML:
  1. <img src="test.jpg" alt="Test image" id="testImage" width="500" height="333" />
  2.  
  3.     <script type="text/javascript" language="javascript">
  4.     Event.observe( window, 'load', function() {
  5.         new Cropper.Img(
  6.             'testImage',
  7.             { onEndCrop: onEndCrop }
  8.         );
  9.     } );
  10. </script>

Minimum dimensions

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

HTML:
  1. <img src="test.jpg" alt="Test image" id="testImage" width="500" height="333" />
  2.  
  3. <script type="text/javascript" language="javascript">
  4.     Event.observe( window, 'load', function() {
  5.         new Cropper.Img(
  6.             'testImage',
  7.             {
  8.                 minWidth: 220,
  9.                 minHeight: 120,
  10.                 onEndCrop: onEndCrop
  11.             }
  12.         );
  13.     } );
  14. </script>

Select area ratio

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

HTML:
  1. <img src="test.jpg" alt="Test image" id="testImage" width="500" height="333" />
  2.  
  3. <script type="text/javascript" language="javascript">
  4.     Event.observe( window, 'load', function() {
  5.         new Cropper.Img(
  6.             'testImage',
  7.             {
  8.                 ratioDim: {
  9.                     x: 220,
  10.                     y: 165
  11.                 },
  12.                 displayOnInit: true,
  13.                 onEndCrop: onEndCrop
  14.             }
  15.         );
  16.     } );
  17. </script>

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.

HTML:
  1. <img src="test.jpg" alt="Test image" id="testImage" width="500" height="333" />
  2. <div id="previewWrap"></div>
  3.  
  4. <script type="text/javascript" language="javascript">
  5.     Event.observe( window, 'load', function() {
  6.         new Cropper.ImgWithPreview(
  7.             'testImage',
  8.             {
  9.                 previewWrap: 'previewWrap',
  10.                 minWidth: 120,
  11.                 minHeight: 120,
  12.                 ratioDim: { x: 200, y: 120 },
  13.                 onEndCrop: onEndCrop
  14.             }
  15.         );
  16.     } );
  17. </script>

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.

Websites of Interest: SEO Agency advanced JavaScript experience can enhance your site functionality. Adding the JavaScript Image Cropper is a good way to improve the user experience.

Next Steps

Feature Requests & Bug Reports

Please check the existing list of feature requests & bugs and the discussion list before posting requests or reporting bugs.

Leave a Tip

If you find this code useful you can leave a donation towards the continued development & support.

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.

Click here to lend your support to: JavaScript Image Cropper V2 fund raising and make a donation at www.pledgie.com !

Discussion

Note: Please only use the comments for general comments and the discussion list to discuss this code project (e.g. implementation queries, change suggestions etc.).

Comments

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

Pages: « 2519 18 17 16 15 [14] 13 12 11 10 91 » Show All

280. Luke Goodere - 2nd Aug 2007 - 9:02 pm

Hi, your script is very close to what IM looking for, with a slight modification, is it possible to use your crop preview window to move the image about?

I want users to upload images, which will then be created into thumbnails of a set size. I’d love to use your preview window so they can for example center it on their faces, can this be done only using the crop preview window?

Thanks, Luke

279. bjhoern - 2nd Aug 2007 - 3:50 pm

Hello,
I have a problem with it: I’m using the package from above, that means prototype 1.5 and scriptalicious 1.6 or sth like that …
everythings working fine except showing the preview of the cropped image. I’m displaying the image that has to be cropped via

Is this the problem? I cannot use since the image is in an htaccess protected directory and so I have to read it out via a PHP script, that sends also the right image header … so it shouldn’t be the problem but I dunno …

My whole code:

// setup the callback function
function onEndCrop( coords, dimensions ) {
$( ‘x1’ ).value = coords.x1;
$( ‘y1’ ).value = coords.y1;
$( ‘x2’ ).value = coords.x2;
$( ‘y2’ ).value = coords.y2;
$( ‘width’ ).value = dimensions.width;
$( ‘height’ ).value = dimensions.height;
}
Event.observe(window, ‘load’, function() {
new Cropper.Img(
‘testImage’,
{
displayOnInit: true,
previewWrap: ‘previewWrap’,
minWidth: 120,

minHeight: 120,
ratioDim: { x: 120, y: 120 },
onEndCrop: onEndCrop
}
);
} );

278. Westy - 31st Jul 2007 - 6:38 am

I think Dave means he just had to include the effects.js scriptaculous file – rather than just calling src=”../lib/scriptaculous.js?load=builder,dragdrop” he added the effects.js also.

I was able to get it working just fine on the latest release (prototype 1.5.1 and scriptaculous v1.7.1_beta3)... I had a bug in my code. I did run into some problems on Safari though.

Maybe someone can help me:
Due to the way my cropper is getting created (returned from an Ajax call) I decided to just call new Cropper.Img(...); rather than using the Event.observe(...); method as used in the examples. This seemed to work just fine in all browsers except in Safari. Any ideas? I have instead had to create the function myself and call it directly

beginCropper = function(){
new Cropper.Img(...); and then wrote an onclick method to activate the beginCropper method. Any ideas how to get around this limitation? Am I doing something wrong? I can’t seem to use the Event.observer() method and get the cropper to instantiate when being returned from an Ajax call (meaning the JS is returned from the Ajax call and I’m evaluating with the evalScripts: true attribute in the the Ajax.Updater() method. Thanks, and sorry for the confusion earlier… very nice tool Dave!

277. wozzzzza - 30th Jul 2007 - 11:16 pm

so dave, you got the code you can share with us how you added this effects module?? be good to get that.

276. Dave - 30th Jul 2007 - 7:45 pm

I tried the cropper earlier today with the latest stable version of script.aculo.us (1.7.0) and prototype that comes with it (1.5.0) and the only change I had to make to get the tests working was include the effects module of script.aculo.us.

275. p palmer - 30th Jul 2007 - 5:26 pm

I second that, it would be great to have an update with
prototype 1.5.1.1 and scriptaculous v1.7.1_beta3, which dont currently work with cropper.

274. Westy - 27th Jul 2007 - 7:19 am

I love this tool, but was wondering if you plan to update it so that it will work with the latest prototype/scriptaculous releases? The cropper doesn’t seem to work with prototype 1.5.1 and scriptaculous v1.7.1_beta3.

273. jurciks - 25th Jul 2007 - 10:20 am

has anyone similar script that uses jquery?

272. Cime - 24th Jul 2007 - 12:28 am

Anybody got this to work on top of Google Maps?

271. Matt - 11th Jul 2007 - 8:54 pm

This script works well in firefox, but in IE6 and IE7 it does not load the thumbnail correctly to crop. So instead it loads a black jpg for the thumbnail. Has anyone else had this situation?

270. Ben - 9th Jul 2007 - 8:57 pm

A nice simple feature would be to have a “bull’s eye” or something of the sort that is centered in the crop area. Something like when you’re cropping in photoshop.

Thanks.

269. Frank - 9th Jul 2007 - 1:43 am

@greg , is Cropper.Img the whole image to crop or the the cropped area for the whole image? I thought it should be the whole image since it takes the whole image’s id as one the its constructor parameters. But the Cropper.Img.selArea is the cropped area. Am I right?

268. greg - 6th Jul 2007 - 9:55 am

@Frank : out of the blue and not having tried myself, my first guess would be not to patch this script but rather keep an array of Cropper.Img instances in yours.

267. Frank - 6th Jul 2007 - 3:59 am

Nice JS, Dave.
I’m just wondering how easy to change your library to support multiple crop areas on one single image.

Conceptually, I think I need change selArea property on Cropper.Img object to an array of selArea, and a activeArea to reference to the currently selected selArea. When a new drag action is taken, add current selArea if any to the selArea array, create a new selArea and point activeArea to the new selArea. A new style needs to be added for the deactivated selAreas

Is that right? I’m not a JS expert, could you point the direction to me?

Thanks

266. ste - 5th Jul 2007 - 1:08 pm

if($cropWidth <= 0) { $cropWidth = $imageWidth; }

if($cropHeight <= 0) { $cropHeight = $imageHeight; }
if($cropX < 0) $cropX = 0;
if($cropY < 0) $cropY = 0;

265. ste - 5th Jul 2007 - 1:06 pm

Found a bug, where by if you try and crop an image which is already smaller than the minimum size, the resize option would not display the image.

Changing and adding the following fixed the problem in resize_image.php

if($cropWidth

264. Michael Alahverdian - 4th Jul 2007 - 7:11 pm

This is one beautiful piece of script. I was looking for the functionality to then save the thumbnail as a separate file, any thing I missed with that, or just not implemented yet?

263. Kalyan - 4th Jul 2007 - 6:03 am

excellent library.thank you.

262. greg - 4th Jul 2007 - 1:20 am

Well, my guesses turned out completely wrong, and I was under the influence of a badly formed table (yuk) with an unexpected table-layout:fixed… works like a charm now. sorry for the noise.

261. greg - 3rd Jul 2007 - 12:08 am

Hi Dave,

Been enjoying the cropper script for a while now, until recently where someone decided to try and use my stuff with IE7. All simple tests seemed to go smooth, but I keep on bumping into a strange problem now, where the drawArea function can’t be executed, because the areaWidth can’t be properly calculated, because in turn, this.img.width yields a value of 0. By adding a couple of alert()s here in there, the width can in some cases be “retrieved”. It seems as if, when moving the original img element inside the generated wrapper element, the image was reloaded by IE. That’s my only clue, because it is vaguely possible that this specific loading might be somewhat slow-ish. Removing the alert()s or move them around randomly re-causes the problem. Whatever the case, img.complete always returned true, which seem to contradict my suspicions… but then again, I’d never heard of .complete before, and am a bit doubtful about the two last line of the initialize method: I expected that only leaving the else clause’s content would still be working, maybe slightly slower, but it just doesn’t ?

If you had any ideas I could follow, I’d try some more debugging, but it’s pretty much a pita with IE, some I’ll give up at least for tonight.

Pages:« 2519 18 17 16 15 [14] 13 12 11 10 91 » Show All

Leave a comment

No HTML please, only textile. For code please use [lang]...[/lang] tags (e.g. [html]...[/html] for HTML)