Details

Download
Version 1.2.1
Last updated 6th October 2009
Requirements
Demo View demo page
Links
License BSD License
Changelog
1.2.1
  • Added support for latest versions of Prototype & script.aculo.us (1.6.1.0 & 1.8.2 respectively). Changes provided by Tom Hirashima.
  • No-longer package prototype & script.aculo.us with the release
  • Changed tests to use google ajax libraries api to load prototype & script.aculo.us
  • Added option to not auto include the cropper CSS file
  • #00008 - Fixed bug: Dynamic include of cropper CSS expected cropper.js and failed when using cropper.uncompressed.js
  • #00028 - Fixed bug: Doesn't work with latest script.aculo.us - Fix by Tom Hirashima
  • #00030 - Fixed bug: Doesn't work in Firefox 3.5 (CSS include issue)
  • #00007 - Fixed bug: onEndCrop isn't called when moving with keys
  • #00011 - Fixed bug: The image that is to be cropped does not show in IE6.0 -- included CSS fix
  • Tidied up source code & fixed issues that jslint found so it will compress better
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=effects,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.

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.

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

Pages: « 34 … 15 14 13 12 11 [10] 9 8 7 6 5 … 1 » Show All

200. Leif - 23rd Mar 2007 - 10:26 pm

I guess I’m with Craig on this one. Also, is there a way to crop the image first without actually uploading it to the server and then save the preview thumbnail as an image to the server once submitted?

199. Leif - 23rd Mar 2007 - 10:23 pm

Okay, so this is nice. Once you have the area you want cropped on an image located in your server directory, how do you actually crop it and resize it to that. Say I want to resize it to whatever the preview looks like and resave that image file.

198. Craig - 23rd Mar 2007 - 8:29 pm

Ok I need help here. I need to figure out how to save the preview thumbnail to a file. I have the cropper working using a dynamic source and I need to be able to save the area selected to a jpg. I know this cropper is just the UI but I need to understand how to past the information to a PHP script to do something like imagecreate( ). I’m not very good with JS. So if someone could help that would be great.

Thanks

197. riya - 22nd Mar 2007 - 3:26 am

Can anyone give example on how to use “onloadCoords” for the coordinates of the select area to display onload?

Thanks.
Riya

196. Chris - 20th Mar 2007 - 4:47 pm

Hi,
I want to use a fix size rectangle:
displayOnInit: true,
minWidth: 120,
minHeight: 120,
maxWidth: 120,
maxHeight: 120,
onEndCrop: onEndCrop

But I can resize the rectangle. The min works but not the max.

Can someone help me, please?

Regards
Chris

195. Daniel - 19th Mar 2007 - 1:35 am

When using the preview, if you dynamically change the image source, the preview is not updated. This may sound like a rare event, but in my case I run graphical filters on demand and wrap the img src on complete.

I added a method that resets the preview. For anyone in need, here’s all it takes:

resetPreview: function() {
this.subInitialize();
this.subDrawArea();
}

194. TheIceman5 - 18th Mar 2007 - 2:00 am

i have a problem with it when i use it in layers, “advanced layer popup” to be exact. http://www.dmxzone.com/ShowDetail.asp?NewsId=12769

when the crop script is put in the layer popup and run from there, when you go and crop the image in internet explorer 6 or 7 the crop area i like an xray and puts a hole through the layers to the page underneath. anyone give me any advice on how to correct this problem?
the demo above works fine, just when you combine the cropper and popup layer is where the problem starts with the xray.

Fulld etails are here in this thread on this forum below.
can anyone help me out here??

http://phpbuilder.com/board/showthread.php?t=10337256

193. Sergey Koksharov - 16th Mar 2007 - 6:56 am

Hey! It’s a really cool cropper. It was surprise for me to knew about that tool cause I did somthing like on http://marqueetool.net
Dave, may be we will cooperate and will create some more powerfull cropper (marquee) or something else? ;)

Regards, Sergey Koksharov

192. Dave - 15th Mar 2007 - 11:30 pm

Dave:
Congratulations on fixing the bug, really well done.

As you say I doubt this is something that I would add to the script itself, maybe only as a note in the usage instructions – as I can’t reliably be messing around with any elements that the script doesn’t create itself.

Well done again.

191. Dave (Different One) - 15th Mar 2007 - 1:24 pm

Dave

tap dances gleefully

ok, the IE/Opera overflow bug….FIX!!!

such a pain in the arse to find, so simple a fix. You need to add ‘position:relative’ to the image container.

I’ve tested this in the latest version if IE/Firefox/Opera and it works a treat. I thought about having cropper.js do it onLoad, but wasn’t sure if you wanted to mess with the container as its a user defined element.

Anyhow, I didn’t say before, so I’ll say it now, excellent script :).

Also, I’ve written an asp.net backend cropper if anyone wants an alternative to the PHP ones out there.

Thanks Muchly

Dave

190. Dave - 13th Mar 2007 - 10:01 am

Daniel:
If memory serves me correctly the handles are just sized and positioned via the CSS so you should be able to change them quite easily.

Dave:
No I’ve not got any further with the overflow issue, I had fixed it completely in Firefox but in IE and Opera the image burst (from a rendering terms, not in the DOM) out of the overflow element when I apply the cropper.

This only happens when I dynamically alter the DOM at runtime, if the HTML that the script inserts is there when the page loads then it is fine in both IE and Opera, this makes absolutely no sense and I couldn’t find a work around to it – I eventually just had to take a break from trying to fix that issue as it was driving me crazy. I can dig out my old test cases and let you have a play if you want.

189. Daniel - 13th Mar 2007 - 3:22 am

Anyway to give the grab boxes some more grab-space? It requires a lot of mouse control when they’re that small.

188. Felix - 12th Mar 2007 - 4:03 am

I just wanted to say thanks!

187. Dave (Different One) - 12th Mar 2007 - 2:28 am

Hya,

Just wondered if you’d got anywhere with the overflow issue, or if you’ve got any ideas why and i’ll dig around and see if i can fix it.

Thanks

Dave

186. Darrell Esau - 8th Mar 2007 - 11:36 pm

Great work.

I’m having one issue that I’ve reproduced in Firefox, Safari and IE:
Everything works great, except when I’ve created a crop rectangle, then try to move the selected area by clicking and dragging. It just reselects another area. Any hints?

185. Dave - 8th Mar 2007 - 4:27 pm

Rob:

I can see that the CSS file is not been loaded as it doesn’t exist, that could possibly be the problem.

184. Bjoern - 8th Mar 2007 - 3:53 pm

Hi,

great work first of all :-)

Would be cool to have an zooming function like here:
http://mypictr.com/

Bye,
Bjoern

183. Rob - 8th Mar 2007 - 3:35 pm

HI,

Ive been having a hell of a time trying to get the cropper to work. I have literally copied and pasted the Cropper Demo page an I have had no success making it work.

If anyone could have a look at it I would really appreciate it.

http://lloveras.org/cropper/test.html

Any one have an idea why it doesnt work?

182. Dan - 5th Mar 2007 - 4:24 pm

I totally understand Dave. It was the first thing I tried when i used it, I just expected a double-click to do my crop because thats what all gfx programs do. Its not necessary or highly important, but it is the norm.

Only other posters could verify the importance of such a feature.

Thanks again Dave

181. Dave - 5th Mar 2007 - 3:41 pm

Dan:
A double click would work, and is something I could potentially add to the release version (as you’d be sure that the user was within the cropper) – I suppose if I add that then I could add an alternative option for the enter key to do the same callback.

However I’m still not sure whether this feature would be used by only the minority of people using the cropper and I don’t want to bloat the base release with features like this if it’s not going to be used in the majority of implementations.

Pages:« 34 … 15 14 13 12 11 [10] 9 8 7 6 5 … 1 » Show All

Leave a comment

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