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.

Parameter	Description
`wait`	Specifies whether the plugin should wait for files to be processed before submitting the form. This is `false` by default.
`params`	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: `$('#upload-form').transloadit({ wait : true, params : { auth : { key : 'YOUR_TRANSLOADIT_AUTH_KEY' }, steps : { resize_to_75: { robot : '/image/resize', use : ':original', width : 75, height : 75 }, // more Steps here } } });`
`signature`	Specifies the signature string, which is required if signature authentication is enabled in your account. This is `null` by default. The old way of providing this in a hidden input field named `signature` is still valid and will not be deprecated. 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!
`modal`	Specifies whether to render the Transloadit overlay and progress bar automatically. This is `true` by default.
`autoSubmit`	Specifies whether to submit the original form automatically once the upload and processing have completed. This is `true` by default.
`formData`	Specifies whether to use XMLHttpRequest (XHR) for file uploading. This is `false` by default. Can either be a FormData object or `true`, in which case the plugin builds the FormData object.
`processZeroFiles`	Specifies whether to perform processing when the form is submitted with no files selected using the form inputs. This is `true` by default.
`triggerUploadOnFileSelection`	When set to `true` this triggers the upload to Transloadit as soon as the user has selected a file in any of the form's file input fields. This is `false` by default.
`exclude`	Specifies a selector for which any matching `input[type=file]` elements in the current form will not be uploaded through Transloadit. This is `""` by default.
`fields`	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: `$('form').transloadit({ // send no form fields; this is the default fields: false });` If you would like to only send some fields, set this parameter to a CSS selector string matching the fields to be sent: `$('form').transloadit({ // only send the fields named "field1" & "field2" fields: 'input[name=field1], input[name=field2]' });` If you would like to send all form fields, set this to true: `$('form').transloadit({ fields: true });` You can also set this to an object of key/value pairs: `$('form').transloadit({ fields: { name : 'John Doe', age : 26 } });` The fields that you send here will be available as `${fields.*}` variables in your Assembly instructions. Learn more about that here.
`debug`	Specifies whether Transloadit errors are displayed to end users. If this is set to `false`, no Transloadit errors will be displayed. Use the `onError` callback to perform your own logging or presentation. This is `true` by default.
`onStart(assembly)`	This is fired whenever an upload begins.
`onFileSelect(fileName, $fileInputField)`	This is fired whenever a user selects a file in file input field.
`onProgress( bytesReceived, bytesExpected )`	This is fired whenever the upload progress is updated, allowing you to render your own upload progress bar.
`onUpload(upload)`	This is fired once for each file uploaded. This is useful for custom renderings of multiple file uploads. Each upload here has an ID field. You can map that back to the `original_id` field of results on the `onResult` callback.
`onResult(step, result)`	This is fired each time a result becomes available for a given Step, and is only available when `wait` is set to `true`. This can be used to show thumbnails for videos or images once they are uploaded. Results here contain a key `original_id`, which maps them back to the ID of the originally uploaded file's ID.
`onCancel()`	This is fired after an upload has been canceled by the user.
`onError(assembly)`	This is fired when upload errors occur.
`onSuccess(assembly)`	This is fired when the plugin has completed an upload. If `wait` is set to `false`, this is fired after the upload finishes. If `wait` is `true`, this is fired once all files have been processed.

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).

transloadit-jquery-sdk

Transloadit jQuery SDK

Basics

Include drag and drop

Customize the progress bar

Unbinding the plugin

How to use XMLHttpRequest

How to add your own localization / other language strings

How to access the internal Transloadit object

Available plugin versions

Latest

Version 2 Latest

Plugin parameters

Contributing

Versioning

Releases

Building

Tests

Dependencies

License

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

Weekly Downloads

Version

License

Last publish

Collaborators

transloadit-jquery-sdk

Transloadit jQuery SDK

Basics

Include drag and drop

Customize the progress bar

Unbinding the plugin

How to use XMLHttpRequest

How to add your own localization / other language strings

How to access the internal Transloadit object

Available plugin versions

Latest

Version 2 Latest

Plugin parameters

Contributing

Versioning

Releases

Building

Tests

Dependencies

License

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Last publish

Collaborators

Weekly Downloads