Burn Widget JS Reference

The Burn Widget allows you to insert the Background Burner UI window (the same UI used on Bonanza.com) within your own website.

Note: The "touch up" functionality only works with browsers that support CanvasRenderingContext2D and FormData. Users of unsupported browsers will be shown a message informing them of the limited functionality.

Mobile support

The Burn Widget plugin even works on mobile devices. To take advantage of the mobile editor, we recommend you include the viewport meta tag on your page.

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0">

Include the javascript bundle

The Burn Widget plugin requires jQuery 1.5.x or later.

<script src='//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js'></script>
<script src='//bonanzapublic.s3.amazonaws.com/assets/burn_bundle.js'></script>

Creating a new BurnWidget object

Using the Burn Widget requires that you instantiate a new BurnWidget object first.

The BurnWidget initialize method takes a hash of options as a required parameter.

Option	Type	Occurrence	Meaning
apiKey	string	Required	Your Bonanza API developer id
userId	string	Required	A unique id that identifies this user within your application
callback	string	Optional	A URL within your application that we should POST to when the burn is complete, as well as when the final mask is selected or changed. It must be a valid URL including the protocol ("http://" or "https://").
onIndex	function	Optionally	Callback to be triggered when requesting all burns for this user. Receives a single parameter: `jsonResponse`. See the Background Burner API Reference for more information on response values.
onShow	function	Optionally	Callback to be triggered after the show/edit burn is popped up. Receives two parameters: `imageSelector`, `jsonResponse`. See the Background Burner API Reference for more information on response values.
onCreate	function	Optionally	Callback to be triggered after a burn is queued/created. We recommend adding your own functionality to save the `id` and `user_id` the returned in `jsonResponse`. Receives two parameters: `imageSelector`, `jsonResponse`. See the Background Burner API Reference for more information on response values.
onSave	function	Optionally	Callback to be triggered after the user selects a final mask. We recommend adding your own functionality to save the `final_result_url` the returned in `jsonResponse`. Receives two parameters: `imageSelector`, `jsonResponse`. See the Background Burner API Reference for more information on response values.
onError	function	Optionally	Callback to be triggered if the API action raises an exception. Receives two parameters: `type`, `message`.

An example of the minimally required parameters.

var burnWidget = new BONZ.BurnWidget({
  apiKey: 'my Bonanza API developer id',
  userId: 'uniqueId'  // A unique id that identifies this user within *your* application
});

Launching the BurnWidget UI

Once you've instantiated a new BurnWidget object, you can call the launch() method.

Calling burnWidget.launch() without any options triggers the Index action.

Option	Type	Occurrence	Meaning
url	url	Optionally	A URL to an image you want to burn. Triggers the Create action
id	integer	Optionally	The ID of the Background Burn for which you want to view the status. Triggers the Show action
image	string	Optionally	A CSS selector (typically an id) for an `img` element on the page. If the image element has a `data-id` attribute the show action will be triggered, otherwise the `src` attribute will be used as the `url` option, and the create action will be triggered.

An example of launching the UI to queue a burn.

burnWidget.launch({ url: 'http://url.to.my/image/to/burn' });

For a more thorough example, please see our Burn Widget example.