Skip to main content

Multiple Files

There are times when you want to allow users to attach multiple files to a single resource, like an album having many photos or a playlist having many songs. Some file attachment libraries provide a special interface for multiple attachments, but Shrine doesn't have one, because it's more flexible to use the "nested attributes" feature of your ORM directly to implement this.

The basic idea is to create a separate table that will have a many-to-one relationship with the main table, and files will be attached on the records in the new table. That way each record from the main table can implicitly have multiple attachments through the associated records.

album1
  photo1
    - attachment1
  photo2
    - attachment2
  photo3
    - attachment3

album2
  photo4
    - attachment4
  photo5
    - attachment5

...

To illustrate, this code will create an album with three photos using nested attributes:

Album.create(
  title: "My Album",
  photos_attributes: [
    { image: File.open("image1.jpg", binmode: true) },
    { image: File.open("image2.jpg", binmode: true) },
    { image: File.open("image3.jpg", binmode: true) },
  ]
)

This design gives you the greatest flexibility, allowing you to support:

  • adding new attachments
  • updating existing attachments
  • removing existing attachments
  • sorting attachments (via a separate position column)
  • having additional fields on attachments (e.g. captions, votes, number of downloads etc.)
  • expanding this to be "many-to-many" relation (e.g. create different playlists from a list of songs, etc)
  • ...

How to Implement​

For the rest of this guide, we will use the example where we have "albums" that can have multiple "photos" in it. The main table is the albums table and the files (or attachments) table will be the photos table.

1. Create the main resource and attachment table​

Let's create a table for the main resource and attachments, and add a foreign key in the attachment table for the main table:

Sequel.migration do
  change do
    create_table :albums do
      primary_key :id

      String :title
    end

    create_table :photos do
      primary_key :id
      foreign_key :album_id, :albums

      String :image_data
    end
  end
end

In the Photo model, create a Shrine attachment attribute named image (:image matches the _data column prefix above):

class Photo < Sequel::Model
  include ImageUploader::Attachment(:image)
end

2. Declare nested attributes​

Using nested attributes is the easiest way to implement any dynamic "one-to-many" association. In the Album model we'll declare a one-to-many relationship to the photos table, and allow it to directly accept attributes for the associated photo records by enabling nested attributes:

class Album < Sequel::Model
  one_to_many :photos
  plugin :association_dependencies, photos: :destroy # destroy photos when album is destroyed

  plugin :nested_attributes
  nested_attributes :photos, destroy: true
end

Documentation on nested attributes:

3. Create the View​

Create a form like you normally do to create the album. To this form we'll add a file field for selecting photos, which will have multiple attribute to allow the user to select multiple files. We'll also display nested fields for already created photos, so that the same form can be used for updating the album/photos as well (they will be submitted under the album[photos_attributes] parameter).

form_for @album, html: { enctype: "multipart/form-data" } do |f|
  f.text_field :title
  f.fields_for :photos do |p| # adds new `album[photos_attributes]` parameter
    p.hidden_field :image, value: p.object.cached_image_data, id: nil
    p.file_field   :image
    p.check_box    :_destroy unless p.object.new_record?
  end
  file_field_tag "files[]", multiple: true
  f.submit "Create"
end

In your controller you should still be able to assign all the attributes to the album, just remember to whitelist the new parameter for the nested attributes, in this case album[photos_attributes].

4a. Form upload​

If you would like to avoid writing JavaScript, you can have selected files uploaded via the form, and then in your controller you can assign them in the format of nested attributes. You'll want to merge these newly uploaded photos with the existing photos params that will come from the nested form fields. This could look something like this:

# In your controller:

# transform the list of uploaded files into a photos attributes hash
new_photos_attributes = params[:files].inject({}) do |hash, file|
  hash.merge!(SecureRandom.hex => { image: file })
end

# merge new photos attributes with existing (`album_params` is whitelisted `params[:album]`)
photos_attributes = album_params[:photos_attributes].to_h.merge(new_photos_attributes)
album_attributes  = album_params.merge(photos_attributes: photos_attributes)

# create the album with photos
Album.create(album_attributes)

In this case you need to make sure your form tag has enctype="multipart/form-data" attributes specified, otherwise form upload won't succeed.

4b. Direct upload​

Alternatively, you can have selected files immediately uploaded to a direct upload endpoint, as soon as they're selected. It's recommended to use Uppy for handling client side file uploads. There are two methods of implementing direct uploads: to your app using the upload_endpoint plugin, or directly to a storage like S3 using the presign_endpoint plugin. See the walkthroughs for setting up simple direct app uploads and direct S3 uploads, as well as the Roda or Rails demo app which implement multiple file uploads.

Once files are uploaded asynchronously, you can dynamically insert photo attachment fields for the image attachment attribute into the form, where the hidden field is filled with uploaded file data in JSON format, just like when doing single direct uploads. The attachment field names should be namespaced according to the convention that the nested attributes feature expects. In this case it should be album[photos_attributes][<uid>], where <uid> is any unique string.

# naming format in which photos fields should be generated and submitted
album[photos_attributes][11111][image] = '{"id":"38k25.jpg","storage":"cache","metadata":{...}}'
album[photos_attributes][29323][image] = '{"id":"sg0fg.jpg","storage":"cache","metadata":{...}}'
album[photos_attributes][34820][image] = '{"id":"041jd.jpg","storage":"cache","metadata":{...}}'

In your controller you don't need to make any changes to handle the nested photos attributes (other than allowing them), your ORM will take care of creating, updating, or removing the associated photos.

Album.create(album_params) # or `params[:album]`

5. Adding Validations​

You can add file validations to the Photo model using the validation_helpers plugin. You just need to make sure that your ORM is configured to automatically validate associated records.

class ImageUploader < Shrine
  plugin :validation_helpers
  plugin :determine_mime_type

  Attacher.validate do
    validate_max_size 10*1024*1024
    validate_mime_type %w[image/jpeg image/png image/webp]
  end
end
class Album < Sequel::Model
  # ... (nested_attributes already enables validating associated photos) ...
end

Note that by default only metadata set on the client side will be available for validations. Shrine will not automatically run metadata extraction for directly uploaded files, as this would require (at least partially) downloading each file from storage, which could be an unwanted performance penalty. If you want metadata to be extracted on the server side, you can load the restore_cached_data plugin which will make metadata extraction run on assignment, or you can extract the metadata manually (e.g. in a background job) using the refresh_metadata plugin.

Conclusion​

Now we have a simple interface for accepting multiple attachments, which internally uses the nested attributes feature of your ORM to create multiple associated records, each with a single attachment. After creation you can also add new attachments, or update and delete existing ones, which the nested attributes feature gives you for free.