transloadit-rails
Fantastic file uploading for your Rails application.
Description
This is the official Rails gem for Transloadit. It allows you to automate uploading files through the Transloadit REST API.
Install
$ gem install transloadit-rails
Getting started
To get started, you need to add the 'transloadit-rails' gem to your Rails project's Gemfile.
$ echo "gem 'transloadit-rails'" >> Gemfile
Now update your bundle and run the generator.
$ bundle install
$ rails g transloadit:install
Configuration
Edit config/transloadit.yml
. It has an auth
section for your transloadit
credentials and a templates
section to define or refer to existing
templates.
auth:
key : '4d2e...'
secret : '8ad1...' # optional, but highly recommended
duration: 1800 # 30 minute validity period for signed upload forms
templates:
# template identified by template_id
s3_store: '4d2e...'
# template defined inline
image_resize:
steps:
resize:
robot : '/image/resize'
width : 320
height: 200
Usage
Refer to the templates with the transloadify
helper. This requires jQuery,
and loads the Transloadit jQuery plugin.
It also uses JavaScript to ensure your form is encoded as multipart/form-data
.
<%= form_for :upload, :html => { :id => 'upload' } do |form| %>
<%= transloadit :s3_store %>
<%= form.label :file, 'File to upload' %>
<%= form.file_field :file %>
<%= form.submit %>
<% end %>
<%= transloadit_jquerify :upload %>
If you want to use the automatic transload parameter decoding, you have to include the Transloadit::Rails::ParamsDecoder module into your controller
class YourController
include Transloadit::Rails::ParamsDecoder
end
that way the param[:transloadit] is automatically decoded for you, if it exists
Tutorial
In this tutorial, you are going to learn how to use transloadit in a freshly setup rails project.
If you haven't already done so, go ahead and install Rails.
$ gem install rails
With rails installed, let's create a new app called 'my_app'.
$ rails new my_app
$ cd my_app
In order to use transloadit in this app, we need to add the gem to our Gemfile and bundle things up.
$ echo "gem 'transloadit-rails'" >> Gemfile
$ bundle install
With that in place, it's time to generate our transloadit configuration, as well as a basic UploadsController and a dummy Upload model.
$ rails g transloadit:install
$ rails g controller uploads new create
$ rails g model upload
$ rake db:migrate
The controller generator we just executed has probably put two GET routes into
your config/routes.rb
. We don't want those, so lets go ahead an overwrite
them with this.
MyApp::Application.routes.draw do
resources :uploads
end
Next we need to configure our config/transloadit.yml
file. For this tutorial,
just put in your credentials, and define an image resize step as indicated
below:
auth:
key : '4d2e...'
secret : '8ad1...'
duration: 1800 # 30 minute validity period for signed upload forms
templates:
image_resize:
steps:
resize:
robot : '/image/resize'
format: 'jpg'
width : 320
height: 200
Note that we encourage you to enable authentication in your Transloadit Account
and put your secret into the config/transloadit.yml
to have your requests
signed.
Alright, time to create our upload form. In order to do that, please open
app/views/uploads/new.html.erb
, and put the following code in:
<%= javascript_include_tag '//ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js' %>
<h1>Upload an image</h1>
<%= form_for Upload.new, :html => { :id => 'upload' } do |form| %>
<%= transloadit :image_resize %>
<%= form.label :file, 'File to upload' %>
<%= form.file_field :file %>
<%= form.submit %>
<% end %>
<%= transloadit_jquerify :upload, :wait => true %>
With this in place, we can modify the app/views/uploads/create.html.erb
view
to render the uploaded and resized image:
<h1>Resized upload image</h1>
<%= image_tag params[:transloadit][:results][:resize].first[:url] %>
In order to use the transloadit params in your controller and views you have to include the ParamsDecoder into your controller. Let's do that for our UploadsController.
Open up app/controllers/uploads_controller.rb
and adapt it like that:
class UploadsController < ApplicationController
include Transloadit::Rails::ParamsDecoder
def new
end
def create
end
end
That's it. If you've followed the steps closely, you should now be able to try your first upload. Don't forget do start your rails server first:
$ rails server
Then go to http://localhost:3000/uploads/new, and upload an image. If you did everything right, you should see the uploaded and resized file as soon as the upload finishes.