You are viewing Jcrop 2.x documentation — click here for legacy v0.9.x

API Overview

The Jcrop API controls every facet of the Jcrop instance. Most integrations will require little, if any, use of the API. Sometimes you'll be using the API without even really knowing it.

Why use the API?

Some developers will feel more comfortable directly interacting with Jcrop via Javascript methods. Others may require more direct access for reasons of developing or debugging Filters or other Jcrop components.

So, what is this "API"?

Jcrop is really a Javascript object. When we refer to the "Jcrop API" we are really talking about the actual underlying object. In the source code, this is referenced as core, because it forms the core of a Jcrop instance.

The Jcrop core performs the following:

  • Creates a new Jcrop instance by attaching to the container
  • Initializes and manages all components used by Jcrop
  • Stores option settings
  • Manages Selections
  • Manages and assigns filters to new Selections
  • Provides a basic instance-wide set of methods

If you study the $.fn.Jcrop declaration, you will see that the jQuery plugin simply wraps the Jcrop object invocation, and performs a few helpful tasks if we are attaching to an image, such as pre-loading.

Obtaining the Jcrop API

From the Jcrop jQuery plugin "loaded" callback

An easy way to expose the API to a particular variable scope is to declare your variable in the outermost scope that you want it accessible in. Then, by way of the magical closure, you can set the variable to the actual Jcrop API when it becomes available:

var options = { bgOpacity: 0.7 };
var jcrop_api;

$('#target').Jcrop(options,function(){
  jcrop_api = this;
});

$('#mybutton').on('click',function(e){
  if (jcrop_api){
    jcrop_api.setSelect([ 10, 10, 100, 100 ]);
  }
});

We've created a Jcrop instance and stored it's API into a variable. Since we have also created an event handler in the same scope, we can access the API within the button click event handler to set the selection coordinates.

Since it waits for image loading to complete, Jcrop may take a few moments to appear. Notice the button click handler in the previous example makes sure jcrop_api is set before calling a method on it.

Another solution to this problem would be to attach any Jcrop-dependent events from within Jcrop "loaded" callback:

var options = { bgOpacity: 0.7 };
var jcrop_api;

$('#target').Jcrop(options,function(){
  jcrop_api = this;
  init_interface();
});

function init_interface(){
  $('#mybutton').on('click',function(e){
    jcrop_api.setSelect([ 10, 10, 100, 100 ]);
  });
}

Return API from Jcrop plugin call

If Jcrop has been attached using the plugin method, there is a simple shorthand for obtaining the API from the orignally targeted element.

var jcrop_api = $('#target').Jcrop('api');

Note: If multiple elements are matched by the selector, only the API attached to the first element will be returned.
If Jcrop is not attached to that element, the return value will be null.

Wherever feasible, it's best to cache the Jcrop API object in a local variable. This is especially important within repetitive loops (like a cropmove event handler), as continuously creating jQuery objects and calling plugins is somewhat expensive.

Manual Invocation

For an example of manual invocation, please refer to the $.fn.Jcrop declaration in the main Jcrop source file. It demonstrates the basic steps the jQuery plugin takes to start an instance of Jcrop.

To invoke manually:

var jcrop_api = $.Jcrop.attach(element,options);
  • Manual invocation always returns the API.
  • Element value can be selector string, HTMLElement, or jQuery object
  • Expects element value already has width and height defined
  • Your milage may vary, suggest using the jQuery plugin

Controlling a Jcrop instance

Now that we have a handle on the API, we can programatically control that Jcrop instance.
There are many methods available, but they are all called the same way:

jcrop_api.setSelect([x,y,w,h]);
jcrop_api.animateTo([x,y,w,h]);
jcrop_api.newSelection();
var b = jcrop_api.getSelection();

By default, most directly called API methods will affect the current active selection and future selections.
For more information about multiple selections, see Managing Selections.

API Method Shorthand

If we know Jcrop is already attached and we know the method we want to call, it's possible to use a shorthand similar to the api argument above, to call a single method.

$('#target').Jcrop('animateTo',[10,10,100,100]);