Voltron::Upload

Voltron upload brings Dropzone JS and logical file upload & committing to rails resources. It is an attempt to solve the issue of dropzone js uploading files immediately, often times before the resource itself has been saved (i.e. - User registration, where one might be able to upload an avatar)

The nice feature of Voltron Upload is that it requires very little additional code outside of what would be required by CarrierWave and gracefully can fall back to default file field inputs in the event that Dropzone is not supported.

Add this line to your application's Gemfile:

gem 'voltron-upload', '~> 0.2.0'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install voltron-upload

Then run the following to create the voltron.rb initializer (if not exists already) and add the upload config:

$ rails g voltron:upload:install

Also, include the necessary js and css by adding the following to your application.js and application.css respectively

//= require voltron-upload

/*
 *= require voltron-upload
 */

If you want to customize the out-of-the-box functionality or styles, you can copy the assets (javascript/css) to your app assets directory by running:

$ rails g voltron:upload:install:assets

Optionlly, you may copy the few out-of-the-box preview template views to your app by running:

$ rails g voltron:upload:install:views

The views will be installed in the directory <rails_root>/app/views/voltron/upload/preview/

Voltron upload is designed to work as seamlessly as possible with how native carrierwave functionality does. Given a model User, you could have something like the following:

class User < ActiveRecord::Base

  mount_uploader :avatar, AvatarUploader

  mount_uploaders :images, ImageUploader # For multiple uploads

end

Your controller only needs a call to uploadable to include the necessary route actions:

class UsersController < ApplicationController

  uploadable :user

end

The only argument to uploadable is the name of the model you'll be associating the uploads with, and is also optional. If omitted, Voltron Upload will try to determine it by the controller name. A controller named UsersController will look for a model named User, PeopleController will look for a model named Person, etc... If you have any doubts in it's ability to determine the model, just define it like shown above.

Lastly, you need to include the routes in your routes.rb config file:

Rails.application.routes.draw do

  upload_for :people
  
  # Or, explicitly define route parameters

  # Will route the path to 'person#upload' as `upload_people_path`/`upload_people_url`
  upload_for :people, { path: '/person/upload', controller: :person }

end

As for your markup, Voltron Upload overrides the file_field helper method, but the options remain the same so nothing out of the ordinary needs to change. However, additional parameters are possible:

There are two global config settings that will be found in config/initializers/voltron.rb once the installer is run.

Voltron Upload comes preloaded with 3 preview template themes, a horizontal tile layout, vertical tile layout, and progress bar layout. If/when you decide to add new preview templates, they should be added as partial views in the app/views/voltron/upload/preview/ directory. The name of the view then defines the preview name when used in conjunction with the file_field method:

<%= f.file_field :avatar, preview: :horizontal_tile # maps to the _horizontal_tile.html.erb view %>

as well as ties to the associated global config:

Voltron.setup do |config|
  config.upload.previews = {
    horizontal_tile: {
      dictDefaultMessage: 'Drop files here',
      dictCancelUpload: 'Cancel',
      parallelUploads: 10,
      # and so on...
    }
  }
end

If the preview template name defined maps to an existing preview view (in the above case, app/views/voltron/upload/preview/_horizontal_tile.html.erb) an additional css class will be added to the Dropzone wrapper element matching the format dz-layout-<preview name>, i.e. - dz-layout-horizontal_tile

From there, you can theme using the generated class name from within voltron-upload.scss. If the file is not in your assets directory run the views installer to add it. (see Installation above)

Several events are dispatched throughout the course of the upload process, listed with each event's arguments below. Note that in keeping with the Voltron standard of each dispatched object having a data, event, and element parameter, each will appear in the dispatched object. However, whether or not all 3 parameters have content varies. Not all events below have "data" associated, so while data will appear in the dispatched object, it is possible to be empty. See the specifics of each event to understand.

To observe any of the events, simply define the listed callback function in any other Voltron module of your choosing. The single argument will be an object containing the listed data (keys)

Just due to the way CarrierWave caches files, the process of uploading can produce a fair number of caches files. Voltron does not clean up those files itself, so it is up to the developer to implement some sort of cache cleanup process. CarrierWave does provide a clean_cached_files! method that should take care of everything, or one could write a custom rake task to deal with it by means of whenever or some other automated process.

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

Bug reports and pull requests are welcome on GitHub at https://github.com/ehainer/voltron-notify. 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 GNU General Public License.