There are many file uploading gems out there like CarrierWave, Paperclip, and Dragonfly, to name a few. They all have their specifics, and probably you've already used at least one of these gems.
Today, however, I want to introduce a relatively new, but very cool solution called Shrine, created by Janko Marohnić. In contrast to some other similar gems, it has a modular approach, meaning that every feature is packed as a module (or plugin in Shrine's terminology). Want to support validations? Add a plugin. Wish to do some file processing? Add a plugin! I really love this approach as it allows you to easily control which features will be available for which model.
In this article I am going to show you how to:
- integrate Shrine into a Rails application
- configure it (globally and per-model)
- add the ability to upload files
- process files
- add validation rules
- store additional metadata and employ file cloud storage with Amazon S3
The source code for this article is available on GitHub.
The working demo can be found here.
Integrating Shrine
To start off, create a new Rails application without the default testing suite:
rails new FileGuru -T
I will be using Rails 5 for this demo, but most of the concepts apply to versions 3 and 4 as well.
Drop the Shrine gem into your Gemfile:
gem "shrine"
Then run:
bundle install
Now we will require a model that I am going to call Photo
. Shrine stores all file-related information in a special text column ending with a _data
suffix. Create and apply the corresponding migration:
rails g model Photo title:string image_data:text rails db:migrate
Note that for older versions of Rails, the latter command should be:
rake db:migrate
Configuration options for Shrine can be set both globally and per-model. Global settings are done, of course, inside the initializer file. There I am going to hook up the necessary files and plugins. Plugins are used in Shrine to extract pieces of functionality into separate modules, giving you full control of all the available features. For example, there are plugins for validation, image processing, caching attachments, and more.
For now, let's add two plugins: one to support ActiveRecord and another one to set up logging. They are going to be included globally. Also, set up file system storage:
config/initializers/shrine.rb
require "shrine" require "shrine/storage/file_system" Shrine.plugin :activerecord Shrine.plugin :logging, logger: Rails.logger Shrine.storages = { cache: Shrine::Storage::FileSystem.new("public", prefix: "uploads/cache"), store: Shrine::Storage::FileSystem.new("public", prefix: "uploads/store"), }
Logger will simply output some debugging information inside the console for you saying how much time was spent to process a file. This can come in handy.
2015-10-09T20:06:06.676Z #25602: STORE[cache] ImageUploader[:avatar] User[29543] 1 file (0.1s) 2015-10-09T20:06:06.854Z #25602: PROCESS[store]: ImageUploader[:avatar] User[29543] 1-3 files (0.22s) 2015-10-09T20:06:07.133Z #25602: DELETE[destroyed]: ImageUploader[:avatar] User[29543] 3 files (0.07s)
All uploaded files will be stored inside the public/uploads directory. I don't want to track these files in Git, so exclude this folder:
.gitignore
public/uploads
Now create a special "uploader" class that is going to host model-specific settings. For now, this class is going to be empty:
models/image_uploader.rb
class ImageUploader < Shrine end
Lastly, include this class inside the Photo
model:
models/photo.rb
include ImageUploader[:image]
[:image]
adds a virtual attribute that will be used when constructing a form. The above line can be rewritten as:
include ImageUploader.attachment(:image) # or include ImageUploader::Attachment.new(:image)
Nice! Now the model is equipped with Shrine's functionality, and we can proceed to the next step.
Controller, Views, and Routes
For the purposes of this demo, we'll need only one controller to manage photos. The index
page will serve as the root:
pages_controller.rb
class PhotosController < ApplicationController def index @photos = Photo.all end end
The view:
views/photos/index.html.erb
<h1>Photos</h1> <%= link_to 'Add Photo', new_photo_path %> <%= render @photos %>
In order to render the @photos
array, a partial is required:
views/photos/_photo.html.erb
<div> <% if photo.image_data? %> <%= image_tag photo.image_url %> <% end %> <p><%= photo.title %> | <%= link_to 'Edit', edit_photo_path(photo) %></p> </div>
image_data?
is a method presented by Shrine that checks whether a record has an image.
image_url
is yet another Shrine method that simply returns a path to the original image. Of course, it is much better to display a small thumbnail instead, but we will take care of that later.
Add all the necessary routes:
config/routes.rb
resources :photos, only: [:new, :create, :index, :edit, :update] root 'photos#index'
This is it—the groundwork is done, and we can proceed to the interesting part!
Uploading Files
In this section I will show you how to add the functionality to actually upload files. The controller actions are very simple:
photos_controller.rb
def new @photo = Photo.new end def create @photo = Photo.new(photo_params) if @photo.save flash[:success] = 'Photo added!' redirect_to photos_path else render 'new' end end
The only gotcha is that for strong parameters you have to permit the image
virtual attribute, not the image_data
.
photos_controller.rb
private def photo_params params.require(:photo).permit(:title, :image) end
Create the new
view:
views/photos/new.html.erb
<h1>Add photo</h1> <%= render 'form' %>
The form's partial is also trivial:
views/photos/_form.html.erb
<%= form_for @photo do |f| %> <%= render "shared/errors", object: @photo %> <%= f.label :title %> <%= f.text_field :title %> <%= f.label :image %> <%= f.file_field :image %> <%= f.submit %> <% end %>
Once again, note that we are using the image
attribute, not the image_data
.
Lastly, add another partial to display errors:
views/shared/_errors.html.erb
<% if object.errors.any? %> <h3>The following errors were found:</h3> <ul> <% object.errors.full_messages.each do |message| %> <li><%= message %></li> <% end %> </ul> <% end %>
This is pretty much all—you can start uploading images right now.
Validations
Of course, much more work has to be done in order to complete the demo app. The main problem is that the users may upload absolutely any type of file with any size, which is not particularly great. Therefore, add another plugin to support validations:
config/inititalizers/shrine.rb
Shrine.plugin :validation_helpers
Set up the validation logic for the ImageUploader
:
models/image_uploader.rb
Attacher.validate do validate_max_size 1.megabyte, message: "is too large (max is 1 MB)" validate_mime_type_inclusion ['image/jpg', 'image/jpeg', 'image/png'] end
I am permitting only JPG and PNG images less than 1MB to be uploaded. Tweak these rules as you see fit.
MIME Types
Another important thing to note is that, by default, Shrine will determine a file's MIME type using the Content-Type HTTP header. This header is passed by the browser and set only based on the file's extension, which is not always desirable.
If you wish to determine the MIME type based on the file's contents, then use a plugin called determine_mime_type. I will include it inside the uploader class, as other models may not require this functionality:
models/image_uploader.rb
plugin :determine_mime_type
This plugin is going to use Linux's file utility by default.
Caching Attached Images
Currently, when a user sends a form with incorrect data, the form will be displayed again with errors rendered above. The problem, however, is that the attached image will be lost, and the user will need to select it once again. This is very easy to fix using yet another plugin called cached_attachment_data:
models/image_uploader.rb
plugin :cached_attachment_data
Now simply add a hidden field into your form.
views/photos/_form.html.erb
<%= f.hidden_field :image, value: @photo.cached_image_data %> <%= f.label :image %> <%= f.file_field :image %>
Editing a Photo
Now images can be uploaded, but there is no way to edit them, so let's fix it right away. The corresponding controller's actions are somewhat trivial:
photos_controller.rb
def edit @photo = Photo.find(params[:id]) end def update @photo = Photo.find(params[:id]) if @photo.update_attributes(photo_params) flash[:success] = 'Photo edited!' redirect_to photos_path else render 'edit' end end
The same _form
partial will be utilized:
views/photos/edit.html.erb
<h1>Edit Photo</h1> <%= render 'form' %>
Nice, but not enough: users still can't remove an uploaded image. In order to allow this, we'll need—guess what—another plugin:
models/image_uploader.rb
plugin :remove_attachment
It uses a virtual attribute called :remove_image
, so permit it inside the controller:
photos_controller.rb
def photo_params params.require(:photo).permit(:title, :image, :remove_image) end
Now just display a checkbox to remove an image if a record has an attachment in place:
views/photos/_form.html.erb
<% if @photo.image_data? %> Remove attachment: <%= f.check_box :remove_image %> <% end %>
Generating a Thumbnail Image
Currently we display original images, which is not the best approach for previews: photos may be large and occupy too much space. Of course, you could simply employ the CSS width
and height
attributes, but that's a bad idea as well. You see, even if the image is set to be small using styles, the user will still need to download the original file, which might be pretty big.
Therefore, it is much better to generate a small preview image on the server side during the initial upload. This involves two plugins and two additional gems. Firstly, drop in the gems:
gem "image_processing" gem "mini_magick", ">= 4.3.5"
Image_processing is a special gem created by the author of Shrine. It presents some high-level helper methods to manipulate images. This gem, in turn, relies on mini_magick, a Ruby wrapper for ImageMagick. As you've guessed, you'll need ImageMagick on your system in order to run this demo.
Install these new gems:
bundle install
Now include the plugins along with their dependencies:
models/image_uploader.rb
require "image_processing/mini_magick" class ImageUploader < Shrine include ImageProcessing::MiniMagick plugin :processing plugin :versions # other code... end
Processing is the plugin to actually manipulate an image (for example, shrink it, rotate, convert to another format, etc.). Versions, in turn, allows us to have an image in different variants. For this demo, two versions will be stored: "original" and "thumb" (resized to 300x300
).
Here is the code to process an image and store its two versions:
models/image_uploader.rb
class ImageUploader < Shrine process(:store) do |io, context| { original: io, thumb: resize_to_limit!(io.download, 300, 300) } end end
resize_to_limit!
is a method provided by the image_processing gem. It simply shrinks an image down to 300x300
if it is larger and does nothing if it's smaller. Moreover, it keeps the original aspect ratio.
Now when displaying the image, you just need to provide either the :original
or :thumb
argument to the image_url
method:
views/photos/_photo.html.erb
<div> <% if photo.image_data? %> <%= image_tag photo.image_url(:thumb) %> <% end %> <p><%= photo.title %> | <%= link_to 'Edit', edit_photo_path(photo) %></p> </div>
The same can be done inside the form:
views/photos/_form.html.erb
<% if @photo.image_data? %> <%= image_tag @photo.image_url(:thumb) %> Remove attachment: <%= f.check_box :remove_image %> <% end %>
To automatically delete the processed files after uploading is complete, you may add a plugin called delete_raw:
models/image_uploader.rb
plugin :delete_raw
Image's Metadata
Apart from actually rendering an image, you may also fetch its metadata. Let's, for example, display the original photo's size and MIME type:
views/photos/_photo.html.erb
<div> <% if photo.image_data? %> <%= image_tag photo.image_url(:thumb) %> <p> Size <%= photo.image[:original].size %> bytes<br> MIME type <%= photo.image[:original].mime_type %><br> </p> <% end %> <p><%= photo.title %> | <%= link_to 'Edit', edit_photo_path(photo) %></p> </div>
What about its dimensions? Unfortunately, they are not stored by default, but this is possible with a plugin called store_dimensions.
Image's Dimensions
The store_dimensions plugin relies on the fastimage gem, so hook it up now:
gem 'fastimage'
Don't forget to run:
bundle install
Now just include the plugin:
models/image_uploader.rb
plugin :store_dimensions
And display the dimensions using the width
and height
methods:
views/photos/_photo.html.erb
<div> <% if photo.image_data? %> <%= image_tag photo.image_url(:thumb) %> <p> Size <%= photo.image[:original].size %> bytes<br> MIME type <%= photo.image[:original].mime_type %><br> Dimensions <%= "#{photo.image[:original].width}x#{photo.image[:original].height}" %> </p> <% end %> <p><%= photo.title %> | <%= link_to 'Edit', edit_photo_path(photo) %></p> </div>
Also, there is a dimensions
method available that returns an array containing width and height (for example, [500, 750]
).
Moving to the Cloud
Developers often choose cloud services to host uploaded files, and Shrine does present such a possibility. In this section, I will show you how to upload files to Amazon S3.
As the first step, include two more gems into the Gemfile:
gem "aws-sdk", "~> 2.1" group :development do gem 'dotenv-rails' end
aws-sdk is required to work with S3's SDK, whereas dotenv-rails will be used to manage environment variables in development.
bundle install
Before proceeding, you should obtain a key pair to access S3 via API. To get it, sign in (or sign up) to Amazon Web Services Console and navigate to Security Credentials > Users. Create a user with permissions to manipulate files on S3. Here is the simple policy presenting full access to S3:
{ "Version": "2016-11-14", "Statement": [ { "Effect": "Allow", "Action": "s3:*", "Resource": "*" } ] }
Download the created user's key pair. Alternatively, you might use root access keys, but I strongly discourage you from doing that as it's very insecure.
Next, create an S3 bucket to host your files and add a file into the project's root to host your configuration:
.env
S3_KEY=YOUR_KEY S3_SECRET=YOUR_SECRET S3_BUCKET=YOUR_BUCKET S3_REGION=YOUR_REGION
Never ever expose this file to the public, and make sure you exclude it from Git:
.gitignore
.env
Now modify Shrine's global configuration and introduce a new storage:
config/initializers/shrine.rb
require "shrine" require "shrine/storage/s3" s3_options = { access_key_id: ENV['S3_KEY'], secret_access_key: ENV['S3_SECRET'], region: ENV['S3_REGION'], bucket: ENV['S3_BUCKET'], } Shrine.storages = { cache: Shrine::Storage::S3.new(prefix: "cache", **s3_options), store: Shrine::Storage::S3.new(prefix: "store", **s3_options), }
That's it! No changes have to be made to the other parts of the app, and you can test this new storage right away. If you are receiving errors from S3 related to incorrect keys, make sure you accurately copied the key and secret, without any trailing spaces and invisible special symbols.
Conclusion
We've come to the end of this article. Hopefully, by now you feel much confident in using Shrine and are eager to employ it in one of your projects. We have discussed many of this gem's features, but there are even more, like the ability to store additional context along with files and the direct upload mechanism.
Therefore, do browse Shrine's documentation and its official website, which thoroughly describes all available plugins. If you have other questions left about this gem, don't hesitate to post them. I thank you for staying with me, and I'll see you soon!
by Ilya Bodrov via Envato Tuts+ Code
No comments:
Post a Comment