A Rails Integration for Transloadit's file uploading and encoding service
Transloadit is a service that helps you handle file uploads, resize, crop and watermark your images, make GIFs, transcode your videos, extract thumbnails, generate audio waveforms, and so much more. In short, Transloadit is the Swiss Army Knife for your files.
This is a Rails SDK to make it easy to talk to the Transloadit REST API.
This gem provides browser integration. If you're looking to integrate Transloadit from your own serverside Ruby code checkout the ruby-sdk.
$ gem install transloadit-railsor add the transloadit-rails Gem to your Rails project's Gemfile and update your bundle.
$ echo "gem 'transloadit-rails'" >> Gemfile
$ bundle installAfter installation you need to run the transloadit:install generator to complete the setup.
$ rails g transloadit:installEdit config/transloadit.yml. It has an auth section for your transloadit
credentials and a templates section to define or refer to existing
templates. It is highly recommended to enable authentication and signing for
the upload forms.
auth:
key : 'TRANSLOADIT_KEY'
secret : 'TRANSLOADIT_SECRET' # optional, but highly recommended
duration: 1800 # 30 minute validity period for signed upload forms
templates:
# template identified by template_id
s3_store: 'YOUR_TEMPLATE_ID'
# template defined inline
image_resize:
steps:
resize:
robot : '/image/resize'
width : 320
height: 200The transloadit configurations can be further broken up by environment tags to match the environments used by the application (i.e. development, test, production).
Please note, the environment tags must match the application's environments exactly in order to be used.
development:
auth:
key : 'TRANSLOADIT_KEY'
...
templates:
s3_store: 'YOUR_TEMPLATE_ID'
...
production:
auth:
key : 'TRANSLOADIT_KEY'
...
templates:
s3_store: 'YOUR_TEMPLATE_ID'
...Refer to the Templates (which you have set in the config) with the transloadit helper.
<%= form_for :upload, :html => { :id => 'upload' } do |form| %>
<%= transloadit :s3_store %>
<%= form.label :file, 'File to upload' %>
<%= form.file_field :file %>
<%= form.submit %>
<% end %>
<%= javascript_include_tag '//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js' %>
<%= transloadit_jquerify :upload %>This requires jQuery, and loads the Transloadit jQuery plugin. Be sure to exclude the <%= javascript_include_tag '//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js' %> tag if you already have jQuery loaded.
JavaScript also ensures your form is encoded as multipart/form-data.
If you want to use the automatic transloadit parameter decoding, you have to include
the Transloadit::Rails::ParamsDecoder module into your controller
class YourController
include Transloadit::Rails::ParamsDecoder
endThat way the param[:transloadit] is automatically decoded for you, if it exists.
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 railsWith rails installed, let's create a new app called 'my_app'.
$ rails new my_app
$ cd my_appIn 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 installWith 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:migrateThe 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
endNext 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: 200Note 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.9.1/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
endThat'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 serverThen 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.
An example rails application following the tutorial above can be found in the examples directory.
If you want to test your file uploads without relying on the network (a
good idea to keep them fast and lean) you can include some request spec
helpers to allow you to easily populate the transloadit_params and
params[:transloadit] in your actions.
First, in your spec/spec_helper.rb :
require 'transloadit/rspec/helpers'Now, in your request spec :
# NOTE: It's important that you don't use :js => true, otherwise your
# test will actually hit out using AJAX, making your test dependent on the
# network.
it "can upload data files", :js => false do
attach_file 'upload_file', Rails.root.join('spec', 'asset', 'example.pdf')
# UploadsController should be replaced with the actual controller
# you're expecting to POST to when the upload is done
stub_transloadit!(UploadsController, example_json)
click_button 'Submit'
end
def example_json
"{ ... JSON content from a real POST ... }"
endAt a minimum, this gem should work on MRI 2.3.0, 2.2.0, 2.1.0, Rubinius, and JRuby. It may also work on older ruby versions, but support for those Rubies is not guaranteed. If it doesn't work on one of the officially supported Rubies, please file a bug report. Compatibility patches for other Rubies are welcome.
Support for EOL'd Ruby 1.9.x and Ruby 2.0 has been dropped, please use version 1.2.0 if you need support for older Ruby versions.
Testing against these versions is performed automatically by GitHub Actions.
If you have to support IE6 and use a jQuery version below 1.9, you have to change the jquery_sdk_version in the config to 'v1.0.0':
production:
jquery_sdk_version: 'v1.0.0'
auth:
...MIT, see LICENSE
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent