About
Kropper is a free, open-source image cropper for Rails apps by Jonathon Wolfe. It was inspired by the image-cropping UI in Apple's iChat and is best suited for cropping of user profile images or other instances where you want cropped images to have a specific aspect ratio. This demo app manipulates images that are stored with the attachment_fu plugin, but it would be easy to modify it to crop images stored in some other fashion.
Features
- It's easy to use, and it looks pretty sweet.
- Very little Ruby code to add to your app, especially if you're using attachment_fu to handle images.
- It works with either ImageScience or Rmagick as the backend image processor.
- It's been tested in IE 6 & 7, Firefox 1.5 & 2, and Safari 2.0.4.
- You can decide whether images are just cropped to the shape of your cropping stencil, or also resized to actual size of the stencil.
- You can easily change the UI around—the appearance, size, and shape of everyting, including the cropping canvas and cropping stencil, are defined with CSS.
What can I do with this little demo app?
Since I think the most common use of this image cropper would be for cropping user profile images, that's exactly what this demo app lets you do—create and delete 'user' objects and upload/crop their associated 'user_image' objects. So while on the outside it just looks like you're uploading and cropping images, behind the scenes, image files are attached to 'user_image' objects (via attachment_fu) and those 'user_image' objects in turn belong to 'user' objects. Knowing that will make the code much more straightforward.
How the cropping works
While I'm distributing Kropper with the full source of this demo app, the actual cropping action happens in only a few files:
- app/controllers/user_image_controller.rb: on get requests, this controller's crop method simply finds user_image to be cropped and renders the cropping UI (contained in app/views/user_image/crop.rhtml). On post requests, it checks to see if the Cancel button was clicked, and if not, simply passes the form params on to @user_image.crop!.
- app/models/user_image.rb: this is where the actual image cropping happens. The crop! method takes in parameters defining a cropping rectangle in image-space, the size of the onscreen cropping stencil, and whether or not to resize the image to the dimensions of that cropping stencil. crop! crops the image, resizes it if necessary, and saves it back to disk. Attachment_fu automatically updates any thumbnail images after cropping/resizing.
- app/views/user_image/crop.rhtml: this file contains the html for the cropping UI. If you change the DOM ids of the elements inside the form, you'll also have to modify the javascript and CSS files a bit, as they reference these DOM ids. Note: there are a couple of inline IE6-only CSS declarations in this file to get around IE6's crappy support for transparent PNGs. Look for the <!--[if IE 6]> section.
- public/stylesheets/kropper.css: this file defines the size/shape/appearance of the cropping UI—you can change the size, aspect-ratio, and appearance of the cropping canvas, cropping stencil, zoom slider, etc, without changing any html, javascript, or Ruby code. For instance, don't want to use my transparent overlay image (the one with the diagonal lines) but can't be bothered to make your own? Just disable #crop_overlay's background and turn on #crop_stencil's borders. Please note: if you turn on borders or padding for the #crop_stencil or #crop_canvas elements, the width of the borders & padding will be added to the sizes of the elements. For instance, if you set #crop_stencil to be 98x98px with a border of 1px on all sides, the total size of the cropping stencil would be 100x100px.
- public/javascripts/kropper.js: this is where most of the action happens. This javascript code centers the image to be cropped around the cropping stencil and installs callbacks that update the necessary form fields based on user interaction. This code requires that prototype.js, effects.js and dom-drag.js be loaded (see app/views/layouts/main.rhtml).
- public/images/kropper: this directory contains all the images for the default Kropper UI.
Who's using it?
Kropper is brand-new, so if you use it, pleae let me know and I'll mention your site/app here. You can reach me at jon at kolossus dot com.
Questions? Comments? Suggestions?
If you find a bug, have a suggestion about a feature to add, are having trouble integrating or modifying this code to fit your Rails app, don't hesitate to drop me a line. You can reach me at jon at kolossus dot com.
Future Improvements
It'd be nice to replace dom-drag.js with Scriptaculous for dragging functionality. I'll get around to it, but if someone wants to submit the changes, that'd be welcomed. dom-drag.js is currently used only for dragging the image and zoom slider around.
Also, I haven't tested this with attachment_fu's database or Amazon S3 backend storage options -- let me know if you try it with them.
License
This code is released under the MIT License.