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
| Version | 1.2.0 |
|---|---|
| Last updated | 30th October 2006 |
| Requirements |
|
| Demo | View demo page |
| Links | |
| License | BSD License |
| Changelog |
|
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:
-
<script type="text/javascript" src="scripts/cropper/lib/prototype.js" language="javascript"></script>
-
<script type="text/javascript" src="scripts/cropper/lib/scriptaculous.js?load=builder,dragdrop" language="javascript"></script>
-
<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:
-
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;
-
}
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.
-
<img src="test.jpg" alt="Test image" id="testImage" width="500" height="333" />
-
-
<script type="text/javascript" language="javascript">
-
Event.observe( window, 'load', function() {
-
new Cropper.Img(
-
'testImage',
-
{
-
ratioDim: {
-
x: 220,
-
y: 165
-
},
-
displayOnInit: true,
-
onEndCrop: onEndCrop
-
}
-
);
-
} );
-
</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.
-
<img src="test.jpg" alt="Test image" id="testImage" width="500" height="333" />
-
<div id="previewWrap"></div>
-
-
<script type="text/javascript" language="javascript">
-
Event.observe( window, 'load', function() {
-
new Cropper.ImgWithPreview(
-
'testImage',
-
{
-
previewWrap: 'previewWrap',
-
minWidth: 120,
-
minHeight: 120,
-
ratioDim: { x: 200, y: 120 },
-
onEndCrop: onEndCrop
-
}
-
);
-
} );
-
</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.
Comments
There have been 508 comments so far, join the discussion.
Pages: « 26 … 11 10 9 8 7 6 5 4 3 [2] 1 » Show All
40. Adam Roth - 17th Jul 2006 - 4:25 am
I tried to call cropper.setAreaCoords(...), and cropper.drawArea(...) as mentioned above, but I end up getting $( this.overlay ) has no properties. Any ideas? I need to draw the cropping box based on previously saved cropping coordinates.
39. Bane - 14th Jul 2006 - 9:58 am
This is really great and usefull tool!
I have just one question, if you set minimum height and width than crop area is constrained to that ratio. Is it possible to set both minimum height and width without having constrained crop area?
38. nation-x - 11th Jul 2006 - 1:13 am
Sorry… I wasn’t trying to say anything bad about the javascript. :) It’s awesome… I just haven’t been working with javascript for awhile.
What I asking about is using aspect ratio for the cropper when the cropper UI has a maximum width of 500px (as an example) but the image is 1000px. handling the thumbnail isn’t an issue. If I am using a minimum width and height (say 120×120) then when I crop the image I can just crop the selected area and then resize the thumb to 120×120. What I noticed is that the preview window is actually showing the correct representation of what I have selected but the cropper UI is showing the large image in the selection. I suppose I could resize the image first before it’s displayed in the cropper UI, but I was hoping that it could just be done without resizing. I think the key is to use the image from the preview area inside of the selection but I am a PHP developer and haven’t worked with javascript in years… and your javascript isn’t simple… it would take me a month to know it intimately enough to modify it to do what I need… lol.
On the other side of that… I am more then willing to chip in the PHP to crop the images. :) I have a sweet class I put together from a couple of different sources. You can see it here. http://php.amnuts.com/forums/viewtopic.php?t=253
37. Dave - 10th Jul 2006 - 9:20 pm
All:
Thanks for your continued kind comments. I’ve also started up a private bug/feature request list for the cropper due to the huge ammount of interest in it, these I will assign priority as I deem fit or based on demand.
John:
I can kind of see the point in having a zoom function, but I can’t see it being worth the overhead to the script at the moment. Maybe if I get more requests in the same vein.
Robert:
“Great work. I wonder how did you manage to do this in 1 and 1/2 weeks…” Erm dedication and doing little else other than this in the majority of my spare time, I wouldn’t like to count the hours I spent on it, but if I were to put standard 9-5 working days against it I’d say 3 or 4 days max. So it’s not that bad, it’s always easier when you get into a groove with something like this.
As for your first question, the cropper doesn’t take scroll offsets into account, you should be able to tweak it quite easily to account for those. I have added this to the feature request list.
Stoyan:
Thanks for the heads up on the ‘remove cropper’ bug, and the feature request, which I’ve added to my list.
Nation-x:
I’m sorry the JavaScript made your head hurt, I feel the uncompressed one is fairly heavily commented and should give good pointers as to what does what. As for your feature request I’m not quite sure what you require, is it that you have a maximum area for the cropper UI (500×500) and any image larger than this would need to be resized? This will make cropping a little different as you’d have to work out the ratio of the cropper to the resized image, but it is do-able. If you clarify your requirements I may add it to the feature request list.
Bala:
At the moment this is just the JavaScript UI, I do have plans to develop the server-side part of a cropping tool & release this, but I’m not sure when I can squeeze that in.
Uberdoer:
Thanks for your very kind comment. I don’t know how much further I can take the examples – I have multiple live ones and the download comes with 6 different examples, or would you just like to see a couple of tutorial like examples?
36. Uberdoer - 10th Jul 2006 - 5:59 pm
Stunning. Well done Dave. You’ll be getting a donation from me for sure!
A few more examples would be good, including a bit on resetting and removing a previous crop region.
35. bala - 10th Jul 2006 - 4:04 pm
Image Cropper features are good, but i need dynamic feature to upload and crop and update the server image with crop image. How I will do this? Guide me
34. nation-x - 10th Jul 2006 - 3:41 pm
I looked at the cropper.js until my head hurt. :) I need to know how to do this… Let’s say I have an image that is 1000×1100… what I would like to do is set the width attribute of the testImage to 500px and crop by aspect ratio with a minimum width and height of 120px. How can I accomplsh this using this cropper? Can I get some help with this? I would greatly appreciate it.
33. Stoyan - 8th Jul 2006 - 5:56 am
Is it possible to define default selected area (wich appears oninit), without using area ratio ?
32. Stoyan - 6th Jul 2006 - 5:42 pm
Press the ‘Remove Cropper’ buton twice on IE and the image dissapears !
I want also to reset the coordinates on ‘Cropper Remove’ how to do that ?
31. Robert - 5th Jul 2006 - 3:07 pm
OK, I did some reading on script.aculo.us. Please, disregard my second question. :-)
30. Robert - 3rd Jul 2006 - 10:38 pm
Great work. I wonder how did you manage to do this in 1 and 1/2 weeks…
Here is my problem: I am trying to implement your cropper in C# .NET. My image (to be cropped) is inside Panel object (which is actually DIV element 400×400px) and if image is bigger then DIV element then I have scroll bars. If I move these scrollbars then drawing of the crop area doesn’t work properly. And error is actually the offset for which I moved the scroll bar. I guess I need to compensate for this movement. Where in your code I need to add these values: vertical and horizontal offset? Is there quick solution to my problem?
Second question is… what is the minimum required for cropper UI to work. Are all those JS files necessary. I am asking because I deleted some of them and everythig was still working fine. (I only need basic cropping functionality)
Thanks.
29. John - 2nd Jul 2006 - 12:02 pm
Nice work!
well, if you could add two buttons to zoom in/out background image, it would be perfect!
28. Dave - 29th Jun 2006 - 8:28 pm
All:
Sorry for the late response to all of your comments, I’ve been away on holiday and have only just recently returned.
Mike:
I’ve not got around to implementing the server side part of the cropper yet, but when I do I’ll make them (CF & PHP) available here. Looking at your script I can’t see any problems, can you email me more details & some example screen shots/code.
Francis:
Do you have more information, browser version etc. or a live example URL, also what do you mean by it was working well before, is this since an upgrade to a newer version of the cropper UI?
Jake:
Thanks for the kind words on the cropper… I may just use that as a pull out quote one day. Also thanks for the heads up on the resize handle cursor problem, I’ve amended it and it will be in the next release.
Georgi:
The BSD License allows proprietary commercial use, and for the software released under the license to be incorporated into proprietary commercial products, but the copyright must be retained and all conditions met. If you do use it in a commercial piece of software that is successful to some degree then it might be good karma to leave an appropriate donation.
Either way keep in touch and if you could give me a heads up with what you’re using it in that’d be great, it’s nice to see your work out in the wild.
Andrew:
Again, thanks for the kind words on the cropper. I had a quick peek at the ModalBox demo on your page and it looks pretty sweet, good luck with it, I also quite liked the design of the pages – although it took me a few seconds to find the demo link.
Aron:
As I said above I haven’t got around to implementing the server side parts of the cropper I had planned to completment the UI, but when I do I will only be implementing them in CF & PHP. If you create a .Net version of the server side part and wish to release it then I’ll link to it from here if you wish.
Phew, that was quite a bit to catch up on… now to sort out my email…
27. Aron - 27th Jun 2006 - 2:23 pm
Has anyone made a ASP or C# script that actually crops the image?
I see the PHP script above, I may just make the .net version.
26. Georgi Kostov - 20th Jun 2006 - 6:22 am
Very good code. I’m really impressed. I need to use it and I’m concerned about the license for using the code as it will probably go into a commercial app.
25. Jake - 19th Jun 2006 - 5:10 pm
This is the coolest script on the web since…, well, probably ever! It works so smoothly and beautifully and has saved me hours and hours of time.
Thought you should know, the cursor for the western handle is set to “e-resize” when you probably want “w-resize”.
24. Andrew Okonetchnikov - 16th Jun 2006 - 1:33 pm
Great work! Thanks!
Take a look also on my JS “ModalBox” component here: http://okonet.ru/projects/modalbox/
Maybe you’ll have some suggestions too. Thanks again!
23. Francis - 12th Jun 2006 - 4:25 pm
Can you tell me why I can’t see the image?? It was working well before…
http://eleves_tim.cmaisonneuve.qc.ca/e0368657/help.jpg
22. Francis - 12th Jun 2006 - 4:22 pm
Do you have an idea why do I can’t see the image
(sorry for my bad english)
Thx
21. Mike Burrell - 12th Jun 2006 - 9:40 am
First off, great script!!
I setup your cropper GUI onto my dev site, and am passing the x1, y1, x2, y2, width, height vars to hidden form fields which are then passed to my PHP script below when the form is submitted.
The final photo is cropped, however I am obviously off somewhere as the cropped image isn’t exactly correct. (It appears slightly smooshed and is off a few pixels possibly.)
Any ideas on what I am doing wrong here would be greatly appreciated!!
My PHP script below:
Leave a comment
No HTML please, only textile. For code please use [lang]...[/lang] tags (e.g. [html]...[/html] for HTML)