Google+

Shineyrock

web design & consultancy

Shineyrock

  1. web design and consultancy

blog

  1. Home
  2. blog
  3. read
  4. Uploading Files With Rails and Shrine
  • dislike -3 26

    Uploading Files With Rails and Shrine

    1. December 2016
    2. Daily
    3. read 834

    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! 

    Photo

    martijn broeders

    founder/ strategic creative at shineyrock web design & consultancy
    e-mail: .(JavaScript must be enabled to view this email address)
    phone: 434 210 0245
    Add a comment...
    Comments

By - category

By - date

Copyright © 1999 - 2026 Shineyrock web design and consultancy, All Rights Reserved / Terms of Conditions / Sitemap: XML, HTML, Images, Mobile, News