Skip to content
Browse files

Add custom form fields support to Transloadit::Assembly, updated READ…

…ME accordingly, added Github syntax highlightning along the way
  • Loading branch information...
1 parent 2731b51 commit fa0f8cf1185d022ff446da68320dbd8643ad5d6b @rmehner rmehner committed Jul 29, 2011
Showing with 136 additions and 59 deletions.
  1. +89 −58 README.md
  2. +2 −1 lib/transloadit/assembly.rb
  3. +45 −0 test/unit/transloadit/test_assembly.rb
View
147 README.md
@@ -9,23 +9,29 @@ you to automate uploading files through the Transloadit REST API.
## Install
- gem install transloadit
+```bash
+gem install transloadit
+```
## Getting started
To get started, you need to require the 'transloadit' gem:
- $ irb -rubygems
- >> require 'transloadit'
- => true
+```bash
+$ irb -rubygems
+>> require 'transloadit'
+=> true
+```
Then create a Transloadit instance, which will maintain your authentication
credentials and allow us to make requests to the API.
- transloadit = Transloadit.new(
- :key => 'transloadit-auth-key',
- :secret => 'transloadit-auth-secret'
- )
+```ruby
+transloadit = Transloadit.new(
+ :key => 'transloadit-auth-key',
+ :secret => 'transloadit-auth-secret'
+)
+```
### 1. Resize and store an image
@@ -35,51 +41,59 @@ and store the result on [Amazon S3](http://aws.amazon.com/s3/).
First, we create two steps: one to resize the image to 320x240, and another to
store the image in our S3 bucket.
- resize = transloadit.step 'resize', '/image/resize',
- :width => 320,
- :height => 240
+```ruby
+resize = transloadit.step 'resize', '/image/resize',
+ :width => 320,
+ :height => 240
- store = transloadit.step 'store', '/s3/store',
- :key => 'aws-access-key-id',
- :secret => 'aws-secret-access-key',
- :bucket => 's3-bucket-name'
+store = transloadit.step 'store', '/s3/store',
+ :key => 'aws-access-key-id',
+ :secret => 'aws-secret-access-key',
+ :bucket => 's3-bucket-name'
+```
Now that we have the steps, we create an assembly (which is just a request to
process a file or set of files) and let Transloadit do the rest.
- assembly = transloadit.assembly(
- :steps => [ resize, store ]
- )
-
- response = assembly.submit! open('lolcat.jpg')
+```ruby
+assembly = transloadit.assembly(
+ :steps => [ resize, store ]
+)
+
+response = assembly.submit! open('lolcat.jpg')
+```
When the `submit!` method returns, the file has been uploaded but may not yet
be done processing. We can use the returned object to check if processing has
completed, or examine other attributes of the request.
- # returns the unique API ID of the assembly
- response[:assembly_id] # => '9bd733a...'
-
- # returns the API URL endpoint for the assembly
- response[:assembly_url] # => 'http://api2.vivian.transloadit.com/assemblies/9bd733a...'
-
- # checks how many bytes were expected / received by transloadit
- response[:bytes_expected] # => 92933
- response[:bytes_received] # => 92933
-
- # checks if all processing has been completed
- response.completed? # => false
-
- # cancels further processing on the assembly
- response.cancel! # => true
+```ruby
+# returns the unique API ID of the assembly
+response[:assembly_id] # => '9bd733a...'
+
+# returns the API URL endpoint for the assembly
+response[:assembly_url] # => 'http://api2.vivian.transloadit.com/assemblies/9bd733a...'
+
+# checks how many bytes were expected / received by transloadit
+response[:bytes_expected] # => 92933
+response[:bytes_received] # => 92933
+
+# checks if all processing has been completed
+response.completed? # => false
+
+# cancels further processing on the assembly
+response.cancel! # => true
+```
It's important to note that none of these queries are "live" (with the
exception of the `cancel!` method). They all check the response given by the
API at the time the assembly was created. You have to explicitly ask the
assembly to reload its results from the API.
- # reloads the response's contents from the REST API
- response.reload!
+```ruby
+# reloads the response's contents from the REST API
+response.reload!
+```
In general, you use hash accessor syntax to query any direct attribute from
the [response](http://transloadit.com/docs/assemblies#response-format).
@@ -93,30 +107,34 @@ Transloadit HTTP API.
Multiple files can be given to the `submit!` method in order to upload more
than one file in the same request. You can also pass a single step for the
`steps` parameter, without having to wrap it in an Array.
-
- assembly = transloadit.assembly(steps: store)
-
- response = assembly.submit!(
- open('puppies.jpg'),
- open('kittens.jpg'),
- open('ferrets.jpg')
- )
+
+```ruby
+assembly = transloadit.assembly(steps: store)
+
+response = assembly.submit!(
+ open('puppies.jpg'),
+ open('kittens.jpg'),
+ open('ferrets.jpg')
+)
+```
### 3. Parallel Assembly
Transloadit allows you to perform several processing steps in parallel. You
-simply need to `use` other steps. Following
+simply need to `use` other steps. Following
[their example](http://transloadit.com/docs/assemblies#special-parameters):
- encode = transloadit.step 'encode', '/video/encode', { ... }
- thumbs = transloadit.step 'thumbs', '/video/thumbs', { ... }
- export = transloadit.step 'store', '/s3/store', { ... }
-
- export.use [ encode, thumbs ]
-
- transloadit.assembly(
- :steps => [ encode, thumbs, export ]
- ).submit! open('ninja-cat.mpg')
+```ruby
+encode = transloadit.step 'encode', '/video/encode', { ... }
+thumbs = transloadit.step 'thumbs', '/video/thumbs', { ... }
+export = transloadit.step 'store', '/s3/store', { ... }
+
+export.use [ encode, thumbs ]
+
+transloadit.assembly(
+ :steps => [ encode, thumbs, export ]
+).submit! open('ninja-cat.mpg')
+```
You can also tell a step to use the original uploaded file by passing the
Symbol `:original` instead of another step.
@@ -129,14 +147,27 @@ Check the YARD documentation for more information on using
Transloadit allows you to use custom [templates](http://transloadit.com/docs/templates)
for recurring encoding tasks. In order to use these do the following:
- transloadit.assembly(
- :template_id => 'YOUR_TEMPLATE_ID'
- ).submit! open('ninja-cat.mpg')
+```ruby
+transloadit.assembly(
+ :template_id => 'YOUR_TEMPLATE_ID'
+).submit! open('ninja-cat.mpg')
+```
You can use your steps together with this template and even use variables.
The [Transloadit documentation](http://transloadit.com/docs/templates#passing-variables-into-a-template) has some nice
examples for that.
+### 5. Using fields
+
+Transloadit allows you to submit form field values that you'll get back in the
+notification. This is quite handy if you want to add additional custom meta data
+to the upload itself. You can use fields like the following:
+
+```ruby
+transloadit.assembly(
+ :fields => {:tag => 'ninjacats'}
+).submit! open('ninja-cat.mpg')
+```
## Documentation
Up-to-date YARD documentation is automatically generated. You can view the
View
3 lib/transloadit/assembly.rb
@@ -52,6 +52,7 @@ def steps
def submit!(*ios)
params = _extract_options!(ios)
payload = { :params => self.to_hash.update(params) }
+ payload.merge!(self.options[:fields]) if self.options[:fields]
# update the payload with file entries
ios.each_with_index {|f, i| payload.update :"file_#{i}" => f }
@@ -81,7 +82,7 @@ def to_hash
self.options.merge(
:auth => self.transloadit.to_hash,
:steps => self.steps
- ).delete_if {|k,v| v.nil? }
+ ).delete_if {|k,v| v.nil? || k == :fields}
end
#
View
45 test/unit/transloadit/test_assembly.rb
@@ -68,6 +68,47 @@
response.headers[:location].must_match %r{^http://foo.bar/}
end
end
+
+ describe 'with additional parameters' do
+ include WebMock::API
+
+ before do
+ stub_request(:post, 'jane.transloadit.com/assemblies')
+ end
+
+ after do
+ WebMock.reset!
+ end
+
+ it 'must allow to send a template id along' do
+ VCR.use_cassette 'fetch_bored' do
+ Transloadit::Assembly.new(
+ @transloadit,
+ :template_id => 'TEMPLATE_ID'
+ ).submit!
+
+ assert_requested(:post, 'jane.transloadit.com/assemblies') do |req|
+ values = values_from_post_body(req.body)
+ JSON.parse(values['params'])['template_id'].must_equal 'TEMPLATE_ID'
+ end
+ end
+ end
+
+ it 'must allow to send the fields hash' do
+ VCR.use_cassette 'fetch_bored' do
+ Transloadit::Assembly.new(
+ @transloadit,
+ :fields => {:tag => 'ninja-cat'}
+ ).submit!
+
+ assert_requested(:post, 'jane.transloadit.com/assemblies') do |req|
+ values = values_from_post_body(req.body)
+ values['tag'].must_equal 'ninja-cat'
+ JSON.parse(values['params'])['fields'].must_be_nil
+ end
+ end
+ end
+ end
end
describe 'with multiple steps' do
@@ -85,3 +126,7 @@
end
end
end
+
+def values_from_post_body(body)
+ Addressable::URI.parse('?' + URI.decode(body)).query_values
+end

0 comments on commit fa0f8cf

Please sign in to comment.
Something went wrong with that request. Please try again.