transloadit-jquery-sdk v1.0.0
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).
8 years ago