How to Create a jQuery Image Cropping Plugin from Scratch - Part II


Web applications need to provide easy-to-use solutions for uploading and manipulating rich content. This process can create difficulties for some users who have minimal photo editing skills. Cropping is one of the most used photo manipulation techniques, and this step-by-step tutorial will cover the entire development process of an image cropping plug-in for the jQuery JavaScript library.

A Quick Recap

In the previous tutorial, we reviewed:

  • how to extend jQuery
  • how to make a plug-in more flexible by using custom options
  • how to create basic image cropping application

Today, we'll take things further and wrap up our plug-in: we'll define more custom option, add callbacks, make the selection draggable and resizable, build a preview pane and a size hint and write some server-side code to crop the image.

Step 1: Adding More Options

Open your jquery.imagecrop.js file located at /resources/js/imageCrop/and add the following code:

We've added more options and two callbacks, onChange and onSelect. These two can be quite useful in retrieving the state of the plug-in.

The Options

Here is a quick rundown of the options we're adding:

  • aspectRatio - Specifies the aspect ratio of the selection (default value is 0).
  • displayPreview - Specifies whether the preview pane is visible or not (default value is false)
  • displaySizeHint - Specifies whether the size hint is visible or not (default value is false)
  • minSize - Specifies the minimum size of the selection (default value is [0, 0])
  • maxSize - Specifies the maximum size of the selection (default value is [0, 0])
  • previewBoundary - Specifies the size of the preview pane (default value is 90)
  • previewFadeOnBlur - Specifies the opacity of the preview pane on blur (default value is 1)
  • previewFadeOnFocus - Specifies the opacity of the preview pane on focus (default value is 0.35)
  • onCahnge - Returns the plug-in's state when the selection is changed
  • onSelect - Returns the plug-in's state when the selection is made

Step 2: Adding More Layers

In this step, we're going to add more layers. Let's begin with the size hint.

We've added two separate layers because we don't want the foreground to be affected by the background opacity.

Now we'll add nine more layers: the resize handlers.

We've initialized a resize handler for each corner and the middle side.

And finally, the preview pane.

We've initialized two layers:

  • the holder, which works as a mask and
  • the preview image, which has the same src as the original image.
Directory tree

We've used the .appendTo() method to insert the preview image at the end of the holder.

Step 3: Enhancing the Interface

First, we'll add two new global variables.

We'll need these variables later, when we update the resizeSelection() function.

In the first part, we only took care of the allowSelect option. Let's handle allowMove and allowResize too.

We've attached the mousedown event to the selection and all resize handlers.

Now we need to write a little more code to update the new layers we've added before.

The updateSizeHint() function treats two cases depending on the specified parameter.

  • If none is specified, the default behavior is to display and update the size hint (if the selection exists).
  • The second behavior is to fade out the hint. This will be used when the user is done with resizing the selection.

On the previous step, we've only initialized the resize handlers. Now we'll place them in the right position.

Similar to the last function, the updateResizeHandlers() tests two cases: hide-all and default. In the first case, we call the .each() method to iterate over the matched elements.

Let's create the updatePreview() function.

The code for the first three cases should be self explanatory. We call the .animate() method to perform a custom animation of a set off CSS properties. Next, we decide the display value and set the position of the preview holder. Then, we scale the preview image to fit the previewBoundary option and calculate its new position.

We need to update the updateCursor() function too.

And now, the last function of this step.

Step 4: Enhancing setSelection()

We'll add just one thing here: support for the preview pane.

We've tested the displayPreview option and used the .mouseenter() and .mouseleave() functions to attach event handlers to the preview holder.

Step 5: Picking the Selection

To make the selection draggable, we need to deduce when the user moves and releases the mouse button.

Also, we've got the selection offset relative to the mouse position. We'll need it later, in the moveSelection() function.

Step 6: Picking the Resize Handlers

The user will be able to resize the selection by picking and dragging one of the resize handlers. And this can be done in two ways: on both axis - if the user chooses to drag a handler from a corner - or on one axis - if the user chooses to drag a handler from the middle of a side.

We've written a case for each resize handler, because each one needs specific settings.

Step 7: Enhancing resizeSelection()

Different from the first version, the resizeSelection() function will be able to test the minimum/maximum size and lock the aspect ratio of the selection.

Additionally, we've invoked the onChange() callback at the end of the function. The getCropData() function returns the current state of the plug-in. We'll write its body a few steps later.

Step 8: Moving the Selection

Now we'll write the moveSelection() function.

Just like before, we've invoked the onChange() callback at the end of the function.

Step 9: Enhancing releaseSelection()

We need to edit the releaseSelection() function too.

We've reset the resize constraints and added support for the preview pane. Also, we've invoked the onSelect() callback in the same manner as we did before with the onChange() function.

Step 10: Getting the Current State

Now, we are almost ready. Let's write the getCropData() function.

We've just written the last function of this file. Save it and prepare for the next step.

Step 11: Minifying the Code

"Minifying the code reduces its size and improves loading time."

In this step, we'll minify the code of our plug-in to reduce its size and improve the loading time. This practice consists in removing unnecessary characters like comments, spaces, newlines and tabs. Two popular tools for minifying JavaScript code are YUI Compressor (which can also minify CSS) and JSMin. We'll use the first one. Also, it is open-source, so you can take a look at the code to understand exactly how it works.

Using the YUI Compressor

YUI Compressor is written in Java, so it doesn't matter which operating system you use. The only requirement is Java >= 1.4. Download the YUI Compressor and extract it in the /resources/js/imageCrop/ folder. Open the command line and change the current working directory to the same path.

If you're using it for the first time you should start by executing the following line in the command line and read the usage instructions.

Now let's minify our code.

Don't forget to replace x.y.z with the YUI Compressor version that you're using. And that's it; wait for it to finish and then close the command line window.

Step 12: Styling the New Elements

Open up /resources/js/imageCrop/jquery.imagecrop.css and add the following lines to it:

We've added some styling for the size hint, preview pane and resize handlers.

Step 13: Testing the Final Result

First, let's load the minified plug-in.

To be able to test the plug-in, we need to somehow get the selection size and position. That's why we'll use onSelect callback; it returns an object with the current state of the plug-in.

The updateForm() function sets the input values and retains it if the selection exists. Next, the validateForm() function tests if the selection exists and displays an alert pop-up if it's needed.

Let's add the form.

We've added a few hidden inputs and a submit button.


In this example, we'll use PHP with the gd library but you can use any other server-side scripting language that supports a graphic library.

Create an empty file, name it crop.php and fire up your editor.

We've used the imagecreatefromjpeg() method to create a new image from the source path and imagecreatetruecolor() to create the output as a true color image. Next, we've called imagecopyresampled() to copy and resize a part of the image with resampling. The current document type is not what we need, so we call the header() function to change it to image/jpeg. The images that aren't needed anymore are destroyed with the imagedestroy() function. With exit(), we stop the execution of the current script.

That's All

We now have a fully customizable jQuery image cropping plug-in that allows the user to make, drag and resize a selection and displays a size hint and a preview pane. And yes, it looks the same even in Internet Explorer 6! So that completes are two-part tutorial! Thanks for reading!