Transloadit jQuery SDK

The official docs for our jQuery plugin / SDK are on the Transloadit website.

Basics

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.

Assuming a form with the ID "upload-form" (from the minimal integration), the jQuery plugin can be used like this:

<script src="//assets.transloadit.com/js/jquery.transloadit2-v2-latest.js"></script>
<script type="text/javascript">
// We call .transloadit() after the DOM is initialized:
$(function() {
  $('#upload-form').transloadit();
});
</script>

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.

Include drag and drop

Please refer to this project to add support for drag and drop.

Customize the progress bar

If you don't like the Transloadit progress bar, you can render your own, like this:

$('#upload-form').transloadit({
  modal: false,
  onProgress: function(bytesReceived, bytesExpected) {
    // render your own progress bar!
    $('#progress')
      .text((bytesReceived / bytesExpected * 100).toFixed(2) + '%');
  },
  onError: function(assembly) {
    alert(assembly.error + ': ' + Assembly.message);
  }
});

If you like the default Transloadit progress bar but just want to change a few colors, customize these css selectors in your own css.

Unbinding the plugin

You can unbind the plugin by calling

$('#upload-form').unbind('submit.transloadit');

How to use XMLHttpRequest

You can either set the formData parameter to true, or supply your own FormData object to it in order to enable xhr file uploads:

$('#upload-form').transloadit({
  formData: true
});

How to add your own localization / other language strings

You can add your own language strings like so:

var $el = $('#upload-form');
$el.transloadit({
  locale: "my_locale"
});

$el.transloadit.i18n.my_locale = {
  'errors.BORED_INSTANCE_ERROR' : 'Could not find a bored instance.',
  'errors.CONNECTION_ERROR'     : 'There was a problem connecting to the upload server',
  'errors.unknown'              : 'There was an internal error.',
  'errors.tryAgain'             : 'Please try your upload again.',
  'errors.troubleshootDetails'  : 'If you would like our help to troubleshoot this, ' +
      'please email us this information:',
  cancel                        : 'Cancel',
  details                       : 'Details',
  startingUpload                : 'Starting upload ...',
  processingFiles               : 'Upload done, now processing files ...',
  uploadProgress                : '%s / %s MB at %s kB/s | %s left'
}

Then just replace the English strings with your custom language strings.

How to access the internal Transloadit object

You can access the internal uploader object to call methods directly on it like so:

var $el = $('#upload-form');
$el.transloadit({
  wait: true
});

var uploader = $el.data('transloadit.uploader');

// then call some methods on the uploader object
uploader.start();
uploader.stop();

// hide the modal if it exists
uploader.hideModal();

// alternatively you could also do it like this
$el.transloadit('start');
$el.transloadit('stop');

Please consult the plugin's source code to see all available methods.

Available plugin versions

Latest

This is always the latest version, and for now points to v2.7.2. This is the recommended version to use. https://assets.transloadit.com/js/jquery.transloadit2-latest.js

Version 2 Latest

This is always the latest version of the 2.x.x branch, and for now points to v2.7.2. https://assets.transloadit.com/js/jquery.transloadit2-v2-latest.js

Plugin parameters

The plugin supports several parameters.

An object of Assembly instructions that should be executed. For examples please check the minimal integration. This is null by default, which means the instructions are read from the hidden input field named params.

Here is an example:

Please make sure the signature is calculated in your back-end code, so that your Transloadit Auth Secret is not exposed in your public JavaScript code!

A CSS selector that specifies the form fields to be sent to Transloadit. This is false by default, which means no form fields are submitted with an upload.

For example:

If you would like to only send some fields, set this parameter to a CSS selector string matching the fields to be sent:

If you would like to send all form fields, set this to true:

You can also set this to an object of key/value pairs:

The fields that you send here will be available as ${fields.*} variables in your Assembly instructions. Learn more about that here.

Each upload here has an ID field. You can map that back to the original_id field of results on the onResult callback.

Results here contain a key original_id, which maps them back to the ID of the originally uploaded file's ID.

Important For very specific use-cases it may help to take a look at the plugin's source code. You can also always ask us to clarify something or help you with integration.

Contributing

Feel free to fork this project. We will happily merge bug fixes or other small improvements. For bigger changes you should probably get in touch with us before you start to avoid not seeing them merged.

Versioning

This project implements the Semantic Versioning guidelines.

Releases will be numbered with the following format:

..

And constructed with the following guidelines:

• Breaking backward compatibility bumps the major (and resets the minor and patch)
• New additions without breaking backward compatibility bumps the minor (and resets the patch)
• Bug fixes and misc changes bumps the patch

For more information on SemVer, please visit http://semver.org/.

latest points to the latest stable of a major version.

Note that the 2 in jquery.transloadit2-latest.js refers to the Transloadit API2 version, not the client SDK version.

Releases

We have two magic releases:

• jquery.transloadit2-latest.js This is always the latest version of any major release and is the recommended version to use. If you use this, it may break backwards compatibility for you once we release the next major version. https://assets.transloadit.com/js/jquery.transloadit2-latest.js

• jquery.transloadit2-v2-latest.js This is always the latest major 2.0 version: https://assets.transloadit.com/js/jquery.transloadit2-v2-latest.js

Here's an overview of all our releases.

Building

Building your own compressed version requires a *nix operation system and curl. We are using the Google Closure REST API for minification.

make

The minified output file can be found in: build/jquery.transloadit2.js.

Tests

To run the tests, install make (via Xcode or build-essentials), CasperJS and Node.js. Then run

make test

Dependencies

This plugin includes the following dependencies:

• jquery.easing.js by George McGinley Smith (BSD License)
• jquery.jsonp.js by Julian Aubourg (MIT License)
• toolbox.expose.js by Tero Piirainen (Public domain)
• json2.js by Douglas Crockford (Public domain)

A big thanks goes to the authors of these fantastic projects!

License

The Transloadit jQuery SDK is licensed under the MIT license. The dependencies have their own licenses (MIT, BSD, PUBLIC DOMAIN).