Details
| Version | 1.2.1 |
|---|---|
| Last updated | 6th October 2009 |
| 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=effects,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.
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.
Comments
There have been 667 comments so far, join the discussion.
Pages: « 34 33 32 31 [30] 29 28 27 26 25 24 … 1 » Show All
600. Wessel Heringa - 1st Oct 2009 - 2:29 pm
Draggable not defined bug:
I’ve been messing around trying to get rid of the ‘draggable not defined’ error message. I found out that when putting the scriptaculous and prototype in the header of the page, and the cropper.js in the body the error is no more.
so like this:
....
599. Me - 24th Sep 2009 - 10:55 am
Thanks Dave. That was indeed an elegant solution and it works great!
598. Dave - 24th Sep 2009 - 9:34 am
@Me:
Simply set the divider image as the background of the crop area with it centred and repeating vertically in your CSS.
597. Me - 23rd Sep 2009 - 6:37 am
Hi,
I want to have a line that would always vertically divide the cropper in two halves like that: http://img36.imageshack.us/i/dvder.jpg/
Could you give me a hint as to how to accomplish this?
Thanks!
596. Adam - 16th Sep 2009 - 4:10 pm
We just had a similiar problem in IE8 only, the fix we applied temporarily was to supply the meta tag to make IE8 behave like IE7
Basically the text fields being populated by onEndCrop started out blank but on entry to the image they got set to a set of coords and then didn’t shift no matter what.
After a shirt amount of debug with basic alerts every shift of the cropper calls onEndCrop twice, the first with the correct coords the second with these static ones
Continuing to look into it
595. Dave - 25th Aug 2009 - 8:03 pm
JungleCoder:
Do you have a working example that I can view.
-D
594. JungleCoder - 25th Aug 2009 - 7:44 pm
This script has been really great and I’m feeling like leaving a tip … but I’ve got one issue that’s nagging me:
I loaded cropper.js script in the main page, but the crop interface (image to be cropped) is uploaded and then displayed via AJAX. And thus I may crop multiple images using the original Cropper.Img.prototype ={...} definition that was loaded in the window.somevar / top.somevar scope.
In Firefox everything works fine, but in IE, onEndCrop will not supply new coords and dimensions, instead they are the coords and dimensions from the last image cropped. No matter how I move the crop tool, onEndCrop gives the same data from the last image. And when I continue to try multiple images, the data is still from the first cropped image.
I tried to destroy the Cropper object and it’s sub objects and redefine them with each image uploaded to be cropped, but I couldn’t get that to work.
Has anyone had this experience or can anyone point me to the solution? Any help would be much appreciated.
Thank you very much,
JC
593. Dave - 19th Aug 2009 - 12:30 pm
Rob,
No it’s not possible, the image cropper is designed for use with images only.
-D
592. Rob - 19th Aug 2009 - 6:37 am
Hi. Does anyone know if it is possible to modify the code so it can capture a web-page crop, rather than just the image that the page contains.
The area outside the image and texts and or including the image.
Thanks
PS. Excellent script
591. Dave - 18th Aug 2009 - 1:11 pm
Jim:
Check out the dynamic example in the tests folder, it has a manager that allows you to change croppers on the fly. It’s not a perfect solution but it should do what you need.
-D
590. Jim Mead - 18th Aug 2009 - 1:08 pm
Hi,
Is it possible to inject options into the cropper once it is created?
I would like to be able to select an option from a list and have that selection change the ratio (and or width/height) without having to reload the page.
For example, by default our page should allow a free crop with no constraints, but on selecting an option from a menu, the cropper should be reset and any new crops should obay the selected ratio (without reloading the page as we are currently doing.)
I suspect this is fairly simple and I am just not seeing something.
Thanks
Any news on v2?
589. Davros - 7th Aug 2009 - 1:14 pm
I love this and it does exactly what i want, but I cannot get it to work at all.
Here is my sample htm
[lang]
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’,
{ onEndCrop: onEndCrop }
);
});
[lang]
but it does nothing, other than I know it’s firing the onEndCrop method.
Can anyone help me out.
588. Tim - 16th Jul 2009 - 3:22 pm
Too bad none of my HTML would display, even after using textile and coding it as HTML as instructed.
587. Namrata - 16th Jul 2009 - 5:56 am
good idea….........
586. Tim - 12th Jul 2009 - 3:32 am
This fixes Firefox 3.5, just add the following to the page where you call copper.js:
[HTML][/html]
585. Tim - 12th Jul 2009 - 3:18 am
Sorry, didn’t like my HTML, this should work:
This is what you put in any page that calls cropper.js
584. Tim - 11th Jul 2009 - 9:07 pm
Another fix for the Firefox 3.5 thing is to simply add the following to the pages that use cropper.js:
(obviously, changing the path if it’s not correct)
You can also remove the following section in cropper.js as simply adding the stylesheet to the page does the same thing. Here’s the section you can remove from cropper.js:
// include the stylesheet
$A( document.getElementsByTagName( ‘script’ ) ).each(
function(s) {
if( s.src.match( /cropper\.js/ ) ) {
var path = s.src.replace( /cropper\.js(.*)?/, ‘’ );
// ‘’;
var style = document.createElement( ‘link’ );
style.rel = ‘stylesheet’;
style.type = ‘text/css’;
style.href = path + ‘cropper.css’;
style.media = ‘screen’;
document.getElementsByTagName( ‘head’ )[0].appendChild( style );
}
}
);
583. Don Mateo - 8th Jul 2009 - 12:49 pm
Hi, I have found a solution for compatibility in Firefox 3.5, you need add :
head = document.getElementsByTagName(‘head’)[0];
CSS = document.createElement(‘link’);
CSS.setAttribute(‘rel’, ‘stylesheet’);
CSS.setAttribute(‘type’, ‘text/css’);
CSS.setAttribute(‘href’, ’/cropper/cropper.css’);
CSS.setAttribute(‘media’, ‘screen’);
head.appendChild(CSS);
In the top of the cropper.js
Enjoy
582. Piush - 8th Jul 2009 - 1:07 am
Good work done..Many ppl would be looking for such a great source for cropping the image..
I added all the necessary js file as defined above and also included them in my asp.net webpage… Also i added the code defined above to make a particular functionality of crop working .. but it is not working … it just displaying the image
Help !!!
581. Tim - 2nd Jul 2009 - 12:08 pm
Thank you that fixed it. It looks like cropper.js is not adding the include for the CSS file in FF 3.5 as it was in FF 3.0.
Leave a comment
No HTML please, only textile. For code please use [lang]...[/lang] tags (e.g. [html]...[/html] for HTML)