4elements, web design and consultancy

  1. Uploading Files With Rails and Dragonfly

    Some time ago I wrote an article Uploading Files With Rails and Shrine that explained how to introduce a file uploading feature into your Rails application with the help of the Shrine gem. There are, however, a bunch of similar solutions available, and one of my favorites is Dragonfly—an easy-to-use uploading solution for Rails and Rack created by Mark Evans. 

    We covered this library early last year but, as with most software, it helps to take a look at libraries from time to time to see what's changed and how we can employ it in our application.

    In this article I will guide you through the setup of Dragonfly and explain how to utilize its main features. You will learn how to:

    • Integrate Dragonfly into your application
    • Configure models to work with Dragonfly
    • Introduce a basic uploading mechanism
    • Introduce validations
    • Generate image thumbnails
    • Perform file processing
    • Store metadata for uploaded files
    • Prepare an application for deployment

    To make things more interesting, we are going to create a small musical application. It will present albums and associated songs that can be managed and played back on the website.

    The source code for this article is available at GitHub. You can also check out the working demo of the application.

    Listing and Managing Albums

    To start off, create a new Rails application without the default testing suite:

    For this article I will be using Rails 5, but most of the described concepts apply to older versions as well.

    Creating the Model, Controller, and Routes

    Our small musical site is going to contain two models: Album and Song. For now, let's create the first one with the following fields:

    • title (string)—contains the album's title
    • singer (string)—album's performer
    • image_uid (string)—a special field to store the album's preview image. This field can be named anything you like, but it must contain the _uid suffix as instructed by the Dragonfly documentation.

    Create and apply the corresponding migration:

    Now let's create a very generic controller to manage albums with all the default actions:

    albums_controller.rb

    Lastly, add the routes:

    config/routes.rb

    Integrating Dragonfly

    It's time for Dragonfly to step into the limelight. First, add the gem into the Gemfile:

    Gemfile

    Run:

    The latter command will create an initializer named dragonfly.rb with the default configuration. We will put it aside for now, but you may read about various options at Dragonfly's official website.

    The next important thing to do is equip our model with Dragonfly's methods. This is done by using the dragonfly_accessor:

    models/album.rb

    Note that here I am saying :image—it directly relates to the image_uid column that we created in the previous section. If you, for example, named your column photo_uid, then the dragonfly_accessor method would need to receive :photo as an argument.

    If you are using Rails 4 or 5, another important step is to mark the :image field (not :image_uid!) as permitted in the controller:

    albums_controller.rb

    This is pretty much it—we are ready to create views and start uploading our files!

    Creating Views

    Start off with the index view:

    views/albums/index.html.erb

    Now the partial:

    views/albums/_album.html.erb

    There are two Dragonfly methods to note here:

    • album.image.url returns the path to the image.
    • album.image_stored? says whether the record has an uploaded file in place.

    Now add the new and edit pages:

    views/albums/new.html.erb

    views/albums/edit.html.erb

    views/albums/_form.html.erb

    The form is nothing fancy, but once again note that we are saying :image, not :image_uid, when rendering the file input.

    Now you may boot the server and test the uploading feature!

    Removing Images

    So the users are able to create and edit albums, but there is a problem: they have no way to remove an image, only to replace it with another one. Luckily, this is very easy to fix by introducing a "remove image" checkbox: 

    views/albums/_form.html.erb

    If the album has an associated image, we display it and render a checkbox. If this checkbox is set, the image will be removed. Note that if your field is named photo_uid, then the corresponding method to remove attachment will be remove_photo. Simple, isn't it?

    The only other thing to do is permit the remove_image attribute in your controller:

    albums_controller.rb

    Adding Validations

    At this stage, everything is working fine, but we're not checking the user's input at all, which is not particularly great. Therefore, let's add validations for the Album model:

    models/album.rb

    validates_property is the Dragonfly method that may check various aspects of your attachment: you may validate a file's extension, MIME type, size, etc.

    Now let's create a generic partial to render the errors that were found:

    views/shared/_errors.html.erb

    Employ this partial inside the form:

    views/albums/_form.html.erb

    Style the fields with errors a bit to visually depict them:

    stylesheets/application.scss

    Retaining an Image Between Requests

    Having introduced validations, we run into yet another problem (quite a typical scenario, eh?): if the user has made mistakes while filling in the form, he or she will need to choose the file again after clicking the Submit button.

    Dragonfly can help you solve this problem as well by using a retained_* hidden field:

    views/albums/_form.html.erb

    Don't forget to permit this field as well:

    albums_controller.rb

    Now the image will be persisted between requests! The only small problem, however, is that the file upload input will still display the "choose a file" message, but this can be fixed with some styling and a dash of JavaScript.

    Processing Images

    Generating Thumbnails

    The images uploaded by our users can have very different dimensions, which can (and probably will) cause a negative impact on the website's design. You probably would like to scale images down to some fixed dimensions, and of course this is possible by utilizing the width and height styles. This is, however, not an optimal approach: the browser will still need to download full-size images and then shrink them.

    Another option (which is usually much better) is to generate image thumbnails with some predefined dimensions on the server. This is really simple to achieve with Dragonfly:

    views/albums/_album.html.erb

    250x250 is, of course, the dimensions, whereas # is the geometry that means "resize and crop if necessary to maintain the aspect ratio with center gravity". You may find information about other geometries on Dragonfly's website.

    The thumb method is powered by ImageMagick—a great solution for creating and manipulating images. Therefore, in order to see the working demo locally, you'll need to install ImageMagick (all major platforms are supported). 

    Support for ImageMagick is enabled by default inside Dragonfly's initializer:

    config/initializers/dragonfly.rb

    Now thumbnails are being generated, but they are not stored anywhere. This means each time a user visits the albums page, thumbnails will be regenerated. There are two ways to overcome this problem: by generating them after the record is saved or by performing generation on the fly.

    The first option involves introducing a new column to store the thumbnail and tweaking the dragonfly_accessor method. Create and apply a new migration:

    Now modify the model:

    models/album.rb

    Note that now the first call to dragonfly_accessor sends a block that actually generates the thumbnail for us and copies it into the image_thumb. Now just use the image_thumb method in your views:

    views/albums/_album.html.erb

    This solution is the simplest, but it's not recommended by the official docs and, what's worse, at the time of writing it does not work with the retained_* fields.

    Therefore, let me show you another option: generating thumbnails on the fly. It involves creating a new model and tweaking Dragonfly's config file. First, the model:

    The thumbs table will host your thumbnails, but they will be generated on demand. To make this happen, we need to redefine the url method inside the Dragonfly initializer:

    config/initializers/dragonfly.rb

    Now add a new album and visit the root page. The first time you do it, the following output will be printed into the logs:

    This effectively means that the thumbnail is being generated for us by ImageMagick. If you reload the page, however, this line won't appear anymore, meaning that the thumbnail was cached! You may read a bit more about this feature on Dragonfly's website.

    More Processing

    You may perform virtually any manipulation to your images after they were uploaded. This can be done inside the after_assign callback. Let's, for example, convert all our images to JPEG format with 90% quality: 

    There are many more actions you can perform: rotate and crop the images, encode with a different format, write text on them, mix with other images (for example, to place a watermark), etc. To see some other examples, refer to the ImageMagick section on the Dragonfly website.

    Uploading and Managing Songs

    Of course, the main part of our musical site is songs, so let's add them now. Each song has a title and a musical file, and it belongs to an album:

    Hook up the Dragonfly methods, as we did for the Album model:

    models/song.rb

    Don't forget to establish a has_many relation:

    models/album.rb

    Add new routes. A song always exists in the scope of an album, so I'll make these routes nested:

    config/routes.rb

    Create a very simple controller (once again, don't forget to permit the track field):

    songs_controller.rb

    Display the songs and a link to add a new one:

    views/albums/show.html.erb

    Code the form:

    views/songs/new.html.erb

    Lastly, add the _song partial:

    views/songs/_song.html.erb

    Here I am using the HTML5 audio tag, which will not work for older browsers. So, if you're aiming to support such browsers, use a polyfill.

    As you see, the whole process is very straightforward. Dragonfly does not really care what type of file you wish to upload; all in you need to do is provide a dragonfly_accessor method, add a proper field, permit it, and render a file input tag.

    Storing Metadata

    When I open a playlist, I expect to see some additional information about each song, like its duration or bitrate. Of course, by default this info is not stored anywhere, but we can fix that quite easily. Dragonfly allows us to provide additional data about each uploaded file and fetch it later by using the meta method.

    Things, however, are a bit more complex when we are working with audio or video, because to fetch their metadata, a special gem streamio-ffmpeg is needed. This gem, in turn, relies on FFmpeg, so in order to proceed you will need to install it on your PC.

    Add streamio-ffmpeg into the Gemfile:

    Gemfile

    Install it:

    Now we can employ the same after_assign callback already seen in the previous sections:

    models/song.rb

    Note that here I am using a path method, not url, because at this point we are working with a tempfile. Next we just extract the song's duration (converting it to minutes and seconds with leading zeros) and its bitrate (converting it to kilobytes per second).

    Lastly, display metadata in the view:

    views/songs/_song.html.erb

    If you check the contents on the public/system/dragonfly folder (the default location to host the uploads), you'll note some .yml files—they are storing all meta information in YAML format.

    Deploying to Heroku

    The last topic we'll cover today is how to prepare your application before deploying to the Heroku cloud platform. The main problem is that Heroku does not allow you to store custom files (like uploads), so we must rely on a cloud storage service like Amazon S3. Luckily, Dragonfly can be integrated with it easily.

    All you need to do is register a new account at AWS (if you don't have it already), create a user with permission to access S3 buckets, and write down the user's key pair in a safe location. You might use a root key pair, but this is really not recommended. Lastly, create an S3 bucket.

    Going back to our Rails application, drop in a new gem:  

    Gemfile 

    Install it:

    Then tweak Dragonfly's configuration to use S3 in a production environment:

    config/initializers/dragonfly.rb

    To provide ENV variables on Heroku, use this command:

    If you wish to test integration with S3 locally, you may use a gem like dotenv-rails to manage environment variables. Remember, however, that your AWS key pair must not be publicly exposed!

    Another small issue I've run into while deploying to Heroku was the absence of FFmpeg. The thing is that when a new Heroku application is being created, it has a set of services that are commonly being used (for example, ImageMagick is available by default). Other services can be installed as Heroku addons or in the form of buildpacks. To add an FFmpeg buildpack, run the following command:

    Now everything is ready, and you can share your musical application with the world!

    Conclusion

    This was a long journey, wasn't it? Today we have discussed Dragonfly—a solution for file uploading in Rails. We have seen its basic setup, some configuration options, thumbnail generation, processing, and metadata storing. Also, we've integrated Dragonfly with the Amazon S3 service and prepared our application for deployment on production.

    Of course, we have not discussed all aspects of Dragonfly in this article, so make sure to browse its official website to find extensive documentation and useful examples. If you have any other questions or are stuck with some code examples, don't hesitate to contact me.

    Thank you for staying with me, and see you soon! 

     

    0 Comments

    Leave a comment › Posted in: Daily

0 Comments

Got anything to add?

(Basic HTML is fine)