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

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

Display code as plain text
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:

Display code as plain text
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.

Display code as plain text
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.

Display code as plain text
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.

Display code as plain text
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.

Display code as plain text
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.

Related Item: 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

Download

Demo

View the demo pages for the JavaScript Image Cropper UI, using Prototype & script.aculo.us

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 513 comments so far, join the discussion.

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

100. Dave - 27th Sep 2006 - 9:29 pm

All:
Thanks for the continued kind words and I apologise for the late replies, things have been a little hectic around here.

Sune:
I’ve just fixed a couple of positioning bugs in the current revision, maybe the next version (possibly to be sometime this week) will fix your problems.

Bill:
The above fixes should solve your problems with the cropper positioning too. I’ll register your onEndCrop callback problem as a bug.

Dan:
I don’t quite get what your suggestion is. I am looking into different solutions to fixed the issues with scaled images however.

Lucas:
I’ll add overflow issues to my test cases, I think my current progress should fix any problems with overflow: auto or overflow: scroll, but overflow hidden will be a different matter I’m sure.

Kennet:
Cheers, glad you like it.

Luke:
Thanks for the kind words, theres a bug with the cropper in your site (in Firefox anyway) as you’re adding borders to the image somehow. This should be fixed in the next release.

Rafael:
Thanks for your comments and the donation, as you’re already aware I’ve fixed the issue with the donation text link. Thanks for pointing that out.

99. Andy Stanberry - 26th Sep 2006 - 11:29 pm

I recently added a class to the mix that supports multiple previews. You can check it out here: Javascript UI Cropper with Multiple Previews

98. Rafael Lima - 22nd Sep 2006 - 7:26 pm

I’ve tried to donate but receie an error from paypal:
“We cannot process this transaction because there is a problem with the PayPal email address supplied by the seller.”

97. Rafael Lima - 22nd Sep 2006 - 7:23 pm

Wonderful!!!

Thanks a lot for your work!

Cheers

96. Luke - 20th Sep 2006 - 2:39 pm

hi Dave,

thought i’d just drop you a line to say i was very impressed with your javascript cropper. i’ve actually used it and built a mini jpg cropping application for anyone to use. it also offers the chance to create an MSN Display picture sized crop which might be useful to some people.

thanks for the great script, it really inspired me to make something useful – you’re fully outlined in the

Display code as plain text
HTML:

  1. about page

.

cheers

Luke

95. Bill Smith - 13th Sep 2006 - 12:16 pm

Hi Dave,

I’ve made quite a bit of progress getting the cropper to work inside a prototype window. There were two things I did (although there may be a better way). The first was to change the calculation of the wrapOffsets to be based on cumulativePosition. Then I registered a callback so that when the window is moved, the wrapOffsets are updated to reflect the new position. This appears to work but may have side effects that I’m unaware of. The main problem I’m currently having is after I create the window and then close it, I call Cropper.Img.remove(). Unfortunately I’m finding that the onEndCrop callback still gets called. If I open a window multiple times, the onEndCrop callback gets called multiple times.

Bill

94. Kennet Primstad - 12th Sep 2006 - 12:19 pm

I just love the image cropper, have been looking for this a long time.
It works just perfekt for my needs.

Thanks….

93. Lucas Young - 11th Sep 2006 - 9:02 pm

Oops, I meant my tag is
div style=”width: 379px; overflow:auto;”
cheers

Lucas

92. Bill Smith - 11th Sep 2006 - 7:57 pm

Hi Dave,

I played with it a bit more today and found that my problem is tied to the getCurPos call. The offset in the dialog is the position of the upper left of the dialog. Any thoughts on how that can be subtracted out of the getCurPos call?

Bill

91. Dan - 11th Sep 2006 - 1:33 pm

What about an added feature, so If you absolutly need to crop on scaled images, you can apply the cropper without an image preview, just the cut drag frame? Will this be possible?

90. Bill Smith - 11th Sep 2006 - 1:23 pm

Hi Dave,

First off, great job on this script. You’ve done some good work here! I’m playing with some code where I want to be able to put the cropper inside of a javascript (virtual) dialog. I’ve played with a couple (iBox, Prototype Window Class) and haven’t had much luck. I finally pulled a dialog library that I’ve been playing with out of mothballs and am starting to have marginal success. In Firefox, the handles for the selected area end up in a different position that where you click. IE has the same problem with the addition if I clear the dialog, then redisplay it, the image disappears. I’m looking into anything that the dialog code is doing that may be causing these problems but I was wondering if you had any thoughts from your side.

You can check out the example

TIA,
Bill

89. Sune Kjaergaard - 11th Sep 2006 - 10:09 am

Hi Dave

I have not been able to pinpoint the exact cause of the bug mentioned earlier, however I do believe it has got something to do with the way the cropper is positioned inside the rather complex table structure. If I move it outside the table the bug doesn’t occur, and similar if I position the containing div absolutely it doesn’t occur either, though of course the known positioning bugs do.
As I am intregrating into an aleready existing CMS, it is not an option to change the layout, or the way it is built (in HTML). Therefore my solution was simply to open the cropper in a new window. Almost to easy huh!?

I’ve also not been able to replicate the bug outside the CMS.

Regards
/Sune

88. Lucas Young - 10th Sep 2006 - 8:30 pm

Hi Dave
Yes, my tag is

is there a better way to do this that will prevent the problems with the cropper?

cheers

Lucas

87. Dave - 10th Sep 2006 - 6:50 pm

Sebastian:
It is possible to create multiple previews, you will have to use the available preview class as a base and tweak it to your needs as this is not something I intend to add to the release.

Miri:
Great, thanks for that, I’ll add IE7 to the list of supported browsers.

Juan Pablo:
The cropper is just the UI for setting the crop co-ordinates to pass to your server-side language, this is where the crop will have to take place.

Lucas:
That must be due to the CSS settings on your containing DIV, are you applying any overflow rules?

Dan:
As for zooming no, not yet, I spent a while looking at it. But basically the way the cropper is attached, at the moment, in non-IE browsers (to address render speed issues in Mac browsers and improve performance in general) make zooming impossible. It is still something I intend to look into.

As for multiple images on the same page, it should be good – I haven’t tested it in a while but it should work fine.

86. Dan - 9th Sep 2006 - 3:11 am

Great, great and great!
Any news with regards to rendering of the selection image when zooming?
How does it handle multiple images on same page, all inline for cropping?

85. Lucas Young - 7th Sep 2006 - 4:41 am

Hi Dave
The cropper works great for me except when I stick it inside a DIV tag. I have a page where the content is inside a tag so the page doesnt extend too high and break. All the cropping is done inside this div. What happens in Firefox/Mac is that the selection area works fine except for the bottom right corner handle – when that’s clicked, the selection box jumps upwards and shrinks…
In IE the image being cropped extends way off the bottom of the div, behind some other page elements, and has the same bottom-right corner handle problem.
Could I do something to fix or prevent this?

many thanks

Lucas

84. Juan Pablo Ruiz - 5th Sep 2006 - 1:30 pm

Excelent script!

I just want to save the cropped file in the server. How can I do that??
Thanks

83. miri - 4th Sep 2006 - 3:18 pm

Just an FYI – one of the people in my test group has IE7 installed. He said he had no problem with the Cropper UI. Yay!

82. sebastian - 4th Sep 2006 - 2:20 pm

Is it somehow possible to create multiple previews? I have to crop a picture and want output a thumbnail of the cropped picture and the cropped picture itself.

Great tool!

81. Dave - 1st Sep 2006 - 10:46 am

Sune:
As with most IE CSS bugs it may be a lot of trial and error, if you have a reliable test case that replicates the problem you could start by removing your custom CSS rules until the bug is fixed. If you have such a test case then you could send it through to me and I’ll try and have a look.

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

Leave a comment

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