[![Build Status](https://travis-ci.org/transloadit/jquery-sdk.svg)](https://travis-ci.org/transloadit/jquery-sdk)

> Warning: We recommend using [Uppy](https://uppy.io/docs/robodog/form/#Migrating-From-the-jQuery-SDK) instead of the jQuery SDK these days.

# Transloadit jQuery SDK

A jQuery Integration for [Transloadit](https://transloadit.com)'s file uploading and encoding service

## Intro

[Transloadit](https://transloadit.com) is a service that helps you handle file uploads, resize, crop and watermark your images, make GIFs, transcode your videos, extract thumbnails, generate audio waveforms, and so much more. In short, [Transloadit](https://transloadit.com) is the Swiss Army Knife for your files.

This is a **jQuery** SDK to make it easy to talk to the [Transloadit](https://transloadit.com) REST API. It supports resumable file uploads out of the box including a modal box with a progress bar, drag and drop support and several other nice things. :)

## Install


  You may also be interested in checking out [Uppy](https://transloadit.com/docs/sdks/uppy/), Transloadit's next-gen file uploader for the web.


Simply include the JavaScript asset in your HTML page like so. jQuery >= 1.9 is also required.

```html


```

## How does it work

You have an HTML form on your page like this one for example:

```

  
  
Drag and drop files here
  

  
  

```

By attaching the jQuery SDK to the form you enable uploading functionality on the form:
```javascript
$('#upload-form').transloadit({
  wait: true,
  triggerUploadOnFileSelection: true,
  params : {
    auth  : { key : 'YOUR_TRANSLOADIT_KEY' },
    template_id : 'YOUR_TEMPLATE_ID'
  }
});
```

Once you select some files over the file input field (or the drag and drop area) a modal will appear that will upload your fils.
The `wait` parameter set to `true` instruct the SDK to wait for all transcoding to finish. Once it's finished it will attach a long JSON
string to a hidden textarea in your form.

You can then submit the form as you normally would. On your backend you have an extra POST field named `"transloadit"` then in the payload including JSON with information about all uploads and transcoding results, their meta data and the URLs to them.

It's that simple. :)

## Version 3

Changes from version 2 to version 3:

### BC Breaking changes:

- The onExecuting() callback does not have the array of `uploads` anymore. Please use the `onUpload` callback to track received uploads.
- The onUpload() and onResult() callbacks no longer receive the assembly object as a parameter.
- The formData parameter has been removed, because all uploads use XHR now. This will only break BC for you if you used formData: customFormDataObj. In that case you should add the contents of your custom form data as hidden input fields to the form now.
- Several new translations have been added for which you would need to add a translation in case you run on a custom locale. Please check "How to add your own localization / other language strings" at the bottom of this page for details.
- There is a new `translations` parameter now that must be used to get your custom locale working.

### Non-BC Breaking Changes and new features:

- There is now support for resumable file uploads! It works out of the box, you do not need to change anything for it.
- Performance has been improved in all areas of the plugin.
- Drag and Drop support has been added.
- Support for file preview lists has been added.
- All options related to polling have been removed.
- There is now a lot less network traffic for assembly status updates.
- There is now the ability to not wait for file upload meta data anymore, which is a big speed improvement. This change was also backported to the last version in the 2.x series.
- There is now a new parameter "maxNumberOfUploadedFiles", with which you can set a limit to the number of uploaded files.
- There are two new callbacks implemented: onDisconnect() and onReconnect()

*Version 2 of the plugin is CEASED TO EXIST on September 30, 2017. Please upgrade to version 3 as soon as possible.*

## Usage

The Transloadit jQuery plugin allows you to

- show file upload progress,
- get uploaded results directly without further API queries, and
- wait for upload processing to complete before redirecting to the result page or calling a callback function.

Assuming a form with the ID `"upload-form"` (from the [minimal integration](https://transloadit.com/docs/#minimal-integration)),
the jQuery plugin can be used like this:

```markup


```

By default, this will display an overlay with a progress bar.

Important Your file input fields must each have a proper name attribute for our jQuery SDK to work properly.

## Specifying Assembly Instructions in the Form

Instead of using the plugin's `params` parameter, you could also have added the Assembly Instructions in a hidden form field named `params`.
Sometimes, especially when your instructions need to be calculated by a back-end language, and also when you want to add [Signature authentication](https://transloadit.com/docs/topics/signature-authentication/) it is easier to specify them directly in the form, than to add them in the call to the jQuery SDK.

The contents of the hidden params field need to be encoded as JSON, with **HTML entities escaped**.
Have your preferred scripting language encode the JSON for you to maintain readability. Here is an example in PHP:

```php
$params = array(
  "auth" => array("key" => "YOUR_TRANSLOADIT_KEY"),
  "steps" => array(
    "resize_to_75" => array(
      "robot" => "/image/resize",
      "use" => ":original",
      "width" => 75,
      "height" => 75
    )
  )
);

printf(
  '',
  htmlentities(json_encode($params))
);
```

Your form should then look like this (just with `YOUR_TRANSLOADIT_KEY` replaced with your real Auth Key):

```markup

  
  
  

```

Both ways of adding the Assembly Instructions are valid. When you upload a file you should see the same result.

## Example

An example use of this plugin can be found in the [examples](https://github.com/transloadit/jquery-sdk/tree/master/examples) directory.

To run it, simply replace `YOUR_TRANSLOADIT_KEY` (on the HTML file) with your actual Transloadit key and load the html file on your browser.

## Releases

We have one *magic* release:

- `jquery.transloadit-v3-latest.js`
  This is always the latest version of the v3 branch and is **the recommended version to use**. 

- You can also pin specific versions via:
  . Remember that it then becomes your responsibility to keep track of security and performance upgrades in our [releases](https://github.com/transloadit/jquery-sdk/releases).

## Callbacks

These can be added as parameters to the `.transloadit()` call like so:

```markup