ClippingMagic.js allows you to conveniently integrate the Clipping Magic editor into your own website. You can edit single images like on the front page, or a sequence of images like in bulk clipping.

Try it out

After you've uploaded a couple of images you can run the examples below right in your browser, just click the "Try it out!"-button.

There are a few minor differences between the regular Clipping Magic editor and the API editor:

  • Custom Default Settings are not available.
  • The help splash screen is not displayed.

To use ClippingMagic.js, start by including and initializing it on the pages where you want to allow editing:

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js" type="text/javascript"></script>
<script src="https://clippingmagic.com/api/v1/ClippingMagic.js" type="text/javascript"></script>
<script type="text/javascript">
  var errorsArray = ClippingMagic.initialize({apiId: 123});
  if (errorsArray.length > 0) alert("Sorry, your browser is missing some required features: \n\n " + errorsArray.join("\n "));
</script>

ClippingMagic.js depends upon jQuery, so be sure to load jQuery before loading ClippingMagic.js.

You can display the editor for a single image like so:

ClippingMagic.edit({
    "image" : {
      "id" : 2345,
      "secret" : "image_secret"
    },
    "locale" : "en-US"
  }, callback);

The callback function will get called with either result-generated or editor-exit, but not both. Both indicate that the editor has been closed.

Be sure to make this call after the document ready event since it references the DOM.

You can display the editor for editing multiple images like so:

ClippingMagic.edit({
    "images" : [ {
      "id" : 2345,
      "secret" : "image_secret"
    }, {
      "id" : 2346,
      "secret" : "image_secret2"
    } ],
    "locale" : "en-US"
  }, callback);

The callback function will get called with result-generated once for each result produced by the user (= once per click on 'Done'). There will be one editor-exit call at the end indicating that the editor has been closed, either by the user clicking the X, or by running out of images to edit. There is no callback for when the user skips an image.

Be sure to make this call after the document ready event since it references the DOM.

The edit function takes a callback function as a parameter. This callback allows you to respond to user actions and notify your backend server about image editing progress.

The signature of the callback is function(opts) and any exceptions or values returned are ignored. The opts parameter is a PlainObject containing:

event
String indicating what just happened, see the table below.
image
Optional. An Image JSON Object (only the id and secret are included).
error
Optional. An Error JSON Object.
EventHas image?Has error?Meaning
result-generatedYesNo The user has clicked 'Done', a result has been generated and is available for immediate download using the backend API. In single-image mode, the editor has been closed.
editor-exitNoNo The user has closed the editor by clicking the red X in the upper right corner, or the user ran out of images to edit in multi-image mode. The editor has been closed.
errorNoYes An error has occurred. Inspect the error value for more information. The editor has been closed.

As soon as the editor has been closed you can call edit() again (calls made prior to that lead to an exception).

Example callback invocation

callback({
  "event" : "result-generated",
  "image" : {
    "id" : 2345,
    "secret" : "image_secret"
  }
}); 

ClippingMagic.initialize(opts) -> array_of_missing_features

The initialize function takes a PlainObject containing key/value pairs that configure the initialization:

apiId
Required. Your API Id.

The function returns a JavaScript Array with strings describing the features that are missing in the current browser, but required to run the editor. If this array is empty, you can go ahead and call the edit function.

ClippingMagic.edit(opts, callback)

The edit function takes the following parameters:

opts

Required. A PlainObject containing key/value pairs that configure the initialization:

image
Optional. An Image JSON Object (only the id and secret are required).
images
Optional. An Array of Image JSON Objects (only the id and secret are required).
locale
Optional. The display language to use for the editor. Defaults to English if omitted. Valid values are:
CodeDisplay Language
en-US English
de-DE Deutsch (German)
es-ES Español (Spanish)
fr-FR Français (French)
it-IT Italiano (Italian)
ja-JP 日本語 (Japanese)
ko-KR 한국어 (Korean)
pt-BR Português (Portuguese)
zh-Hans-CN 简体中文 (Chinese)
callback

Required. See the Callback section above for details.

This method does not return a value. If initialize has not been called before calling this method, or if initialize returned a non-empty array, or if an editor window is already open, then an exception is thrown.


Javascript Error :-(


Please help us fix this issue!