The minimal integration
In the following step by step guide you are going to implement a minimalist image resize upload.
Step 1: Create your account
Please go to our signup page and create an account. Your API credentials are generated automatically for you. Then login to your account.
Step 2: Create a template
Templates contain the instructions that you want to be executed on uploaded files. They are securely stored on our servers and encrypted with 256 bit AES encryption. Nobody looking at your upload form will see any of these instructions - they will just see the id of the template you are using.
To create a template you need to:
- Click on the "Templates" link under "My Account", then click "Create template".
- Give your template a description. This is just for you as a reference.
- Provide the JSON for your template.
- Hit the save button.
Please create a template using the following JSON:
{
"steps": {
"resize_to_75": {
"robot": "/image/resize",
"width": 75,
"height": 75
}
}
}
That will resize any incoming image uploads to 75x75 pixels. It does not store them on Amazon S3 yet, but rather create a temporary file on our servers, which is sufficient for this test.
Hint: On your template page we also have a link "Test it", where you can upload some files to see your template in action and see if it works as expected.
Step 3: Create the upload form
To upload files from your webpage please add the html for a form that points to http://api2.transloadit.com/assemblies:
<form id="MyForm" action="http://api2.transloadit.com/assemblies" enctype="multipart/form-data" method="POST">
<input type="hidden" name="params" value="{"auth":{"key":"your-auth-key"},"template_id":"your-template-id","redirect_url":"http://example.org/upload"}" />
<input type="file" name="my_file" />
<input type="submit" value="Upload">
</form>
Make sure the enctype is multipart/form-data or else browsers will not know that this form is intended to upload files.
The next element is a hidden field called params. The content of it is encoded in json and has all html entities escaped. Here is a more readable version of it:
{
"auth": {
"key": "your-auth-key"
},
"template_id": "your-template-id",
"redirect_url": "http://example.org/upload"
}
You need to replace "your-auth-key" with the key found in My Account -> Account settings -> API credentials and "your-template-id" with the id of the template that you just created. The id can be found on your template list.
Hint: When integrating Transloadit into your app later you should use your favorite scripting language to encode the json. That keeps things readable. Here is an example in php:
$params = array(
'auth' => array('key' => 'your-auth-key'),
'template_id' => 'your-template-id',
'redirect_url' => 'http://example.org/upload'
);
echo '<input type="hidden" name="params" value="' . htmlentities(json_encode($params)) . '" />';
Finally the redirect_url needs to be replaced with a url of your application. It is important that this needs to be a fully qualified url, "/upload" alone will not work.
The redirect_url is the url where Transloadit will submit your form to when it is done processing all uploads.
Step 4: Add the jQuery plugin
The Transloadit jQuery plugin gives you some additional goodness and allows you to:
- show file upload progress,
- get upload results directly without further API queries and
- wait for all encodings or resizings to complete before doing the final form submit.
You can include our jQuery plugin using the following code:
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
<script type="text/javascript" src="//assets.transloadit.com/js/jquery.transloadit2.js"></script>
<script type="text/javascript">
// We call .transloadit() after the DOM is initialized:
$(document).ready(function() {
$('#MyForm').transloadit({
wait: true
});
});
</script>
By default, this will display an overlay with a progress bar when a file is uploaded. The wait parameter determines if Transloadit waits for all files to be processed first before doing the final form submit. In our case that means Transloadit waits for all uploaded files to be resized to 75x75 pixels and then does the final form submit.
Hint: Using the jQuery plugin is completely optional - Transloadit fully works without javascript enabled.
Step 5: Testing
That's it already! You should be all set now to go ahead and submit a file. :) On your backend page print out the incoming POST data to see the results that Transloadit appended to your form.
In PHP for example:
<pre>
<?php
$result = $_POST['transloadit'];
if (ini_get('magic_quotes_gpc') === '1') {
$result = stripslashes($result);
}
print_r(json_decode($result, true));
?>
</pre>
It should be something like this: Show result
(
[ok] => ASSEMBLY_COMPLETED
[message] => The assembly was successfully completed.
[assembly_id] => 9b3e9db9cea55a2a4d07a070a7b489a0
[assembly_url] => http://api2.adia.transloadit.com/assemblies/9b3e9db9cea55a2a4d07a070a7b489a0
[bytes_received] => 16368
[bytes_expected] => 16368
[client_agent] => Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.5; en-US; rv:1.9.2.13) Gecko/20101203 Firefox/3.6.13
[client_ip] => 212.185.232.238
[client_referer] => http://flashfun247.com/tl_test/
[start_date] => 2011/01/11 10:21:42 GMT
[upload_duration] => 0.543
[execution_duration] => 0.123
[fields] => Array
(
)
[uploads] => Array
(
[0] => Array
(
[id] => db3637d9c4cf41cf8d3389f011c72a11
[path] => /mnt/tmp/upload/e96d00a58077e424fc5bef4cb0e60e2c.jpg
[name] => konfetti.jpg
[basename] => konfetti
[ext] => jpg
[size] => 15883
[mime] => image/jpeg
[type] => image
[field] => my_file
[original_id] => db3637d9c4cf41cf8d3389f011c72a11
[url] => http://tmp.adia.transloadit.com/upload/e96d00a58077e424fc5bef4cb0e60e2c.jpg
[meta] => Array
(
[width] => 300
[height] => 304
[date_recorded] =>
...
)
)
)
[last_seq] => 2
[results] => Array
(
[resize_to_75] => Array
(
[0] => Array
(
[id] => 0fa558b6c98db0cfc5b09731bc0a6504
[name] => konfetti.jpg
[basename] => konfetti
[ext] => jpg
[size] => 4281
[mime] => image/jpeg
[type] => image
[field] => my_file
[original_id] => db3637d9c4cf41cf8d3389f011c72a11
[url] => http://tmp.adia.transloadit.com/scratch/1b53037cc4f0c79821a08a9791428ecf
[meta] => Array
(
[width] => 74
[height] => 75
...
)
)
)
)
)
Notice how Transloadit shows you information about both all uploaded files (the uploads key) and all result files that it produced (results key). Once you make your form ready for HTML5-multiupload and have a template with several steps this will come in really handy.
Hint: To see what we just built in action checkout this demo page, where the template is only slightly different.
Step 6: Further reading
This is a minimalist guide on how to integrate Transloadit. You can integrate Transloadit in several ways and that's why you need to make some decisions. The following questions will help you to pick the pages you want to read up on next:
You are all set, but want to read up on all the possible instructions you can build.
Check out the pages for each robot. The Demo section will also help you build your proper instructions. You can also ask us for help anytime.
You need to process dynamic parameters and that's why can't use templates (which cannot be changed at runtime)?
Read up on building assembly instructions.
You want to customize the behavior of the jQuery plugin, for example have your own progress bar and the like?
Check out Configuring the jQuery plugin.
Since processing your uploads takes long - because you have a complicated template and/or are encoding videos - you do not want your users to wait for the processing to be finished before doing the final form submit.
Read up on Notifications vs Redirect Url.