Active Storage Drag and Drop

Provides a form helper to make it easy to make drag and drop file upload fields that work with Rails' ActiveStorage.

• Installation
• Usage
  • Strong Parameters
  • Options
  • Validation
  • JavaScript Events
  • Upload Asynchronously
  • Custom Upload Icons
• Development
• Contributing
• License
• Code of Conduct

Add this line to your application's Gemfile:

gem 'active_storage_drag_and_drop'

And then execute:

$ bundle

Or install it yourself as:

$ gem install active_storage_drag_and_drop

Include the styles in your application css:

/*
 *= require active_storage_drag_and_drop
 */

Include active_stroage_drag_and_drop.js in your application's JavaScript bundle.

//= require active_storage_drag_and_drop

Use yarn to add the js package as a dependency:

$ yarn add active_storage_drag_and_drop

Import the start function from the bundle and run it:

import ActiveStorageDragAndDrop from 'active_storage_drag_and_drop'

ActiveStorageDragAndDrop.start()

Add an ActiveStorage attachment to your model:

class Message < ApplicationRecord
  has_one_attached :image
end

or add multiple ActiveStorage attachments to your model:

class Message < ApplicationRecord
  has_many_attached :images
end

Call the method drag_and_drop_file_field on your model's form:

= form_with model: @message, local: true do |form|
  = form.drag_and_drop_file_field :images
  = form.submit

The first parameter is a symbol representing the method of the ActiveStorage attachment and an optional second parameter sets the text on the drag and drop zone.

form.drag_and_drop_file_field :images, 'Drag and drop images here!'

The content of the dropzone can also be passed as a block of ERB or HAML:

= form.drag_and_drop_file_field :images, disabled: false do
  %i.far.fa-images
  Drag images here!

In your controller you can permit the params like so:

# single file upload
params.permit(:message).require(:image)
# multiple upload
params.permit(:message).require(images: [])

Options for the nested file field can be passed as key value pairs. The helper accepts the same options as the rails file_field form helper ActionView::Helpers::FormHelper#file_field

form.drag_and_drop_file_field :images, nil, disabled: true

Like with the ActionView::Helpers::FormHelper#file_field you can pass a list of acceptable mime-types for client-side validation:

form.drag_and_drop_file_field :images, nil, accept: 'image/png, image/jpeg, image/gif, image/tiff'

An additional size_limit option can be passed which provides validation on the maximum acceptable filesize in bytes:

form.drag_and_drop_file_field :images, nil, size_limit: 5_000_000 # 5MB upper limit on file size

When one of these errors occurs by default a JavaScript 'dnd-upload:error' event is dispatched and an alert detailing the validation error appears. To override this default behaviour listen for the event and call preventDefault() on the event.

To override the default behaviour of any of these events catch them with an event listener and call preventDefault() on the event:

document.addEventListener('dnd-upload:error', function (event) {
  # do something…
  event.preventDefault()
})

To asynchronously trigger uploading without form submission, import the processUploadQueue function and pass the form containing the uploads and a callback function as arguments:

import { processUploadQueue } from 'active_storage_drag_and_drop'

var callback = function(error) {
  if (error) {
    // …handle error…
  } else {
    // …do your stuff
  }
}

processUploadQueue(form, callback)

To customise how the upload icons for each file are added to the DOM you pass an iconPainter option to the start function e.g:

import { start } from 'active_storage_drag_and_drop'

start({
  iconPainter (iconContainer, id, file, complete) {
    iconContainer.insertAdjacentHTML('beforeend', `
    <li data-direct-upload-id="${id}" class="direct-upload">
      <div class="direct-upload__progress" style="width: ${progress}"></div>
      ${file.name}
      <button class="direct-upload__remove">X</button>
    </li>
    `)
  }
})

The arguments that iconPainter receives are:

export function paintDefaultUploadIcon (iconContainer, id, file, complete) {
  const uploadStatus = (complete ? 'complete' : 'pending')
  const progress = (complete ? 100 : 0)
  iconContainer.insertAdjacentHTML('beforeend', `
  <div data-direct-upload-id="${id}">
    <div class="direct-upload direct-upload--${uploadStatus}">
      <div class="direct-upload__progress" style="width: ${progress}%"></div>
      <span class="direct-upload__filename">${file.name}</span>
      <span class="direct-upload__filesize">${fileSizeSI(file.size)}</span>
    </div>
    <a href='remove' class='direct-upload__remove'>X</a>
  </div>
  `)
}

All of the built in UI that manipulates these icons can be overriden by attaching to their event and preventing the default behaviour. But to take advantage of the built in ui events though you should follow these rules:

• The root level element must have a data-direct-upload-id attribute set to the id passed to paintUploadIcon.
• The progress section consists of a parent with the class direct-upload and a direct child with the class direct-upload__progress.
• The element that will cancel the upload when clicked has the class direct-upload__remove.

Install yarn to manage js dependencies. After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Use yarn dev to build JavaScript files automatically on change. Use with gem 'active_storage_drag_and_drop', path: [local-gem-repo] to develop and debug the gem in place in a rails app. You can run the JS tests with yarn test and you can see the coverage as well as the tests by running yarn cover.

After making changes to JavaScript run yarn build before committing changes to transpile the JavaScript for production.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/marinosoftware/active_storage_drag_and_drop. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the ActiveStorageDragAndDrop project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.