voltron-upload 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f264918ab9c54f6a1a5092cde1a7ea0e152a208fcbd71cc138f801fef01944c7
+  data.tar.gz: 53133b595dd837e97017358af5642fd34d2636b0a475c92dfe9fa56ad465910f
+SHA512:
+  metadata.gz: 155183ca91d5eb778f578dd4d98b733b7351e0c8f21cebbb399f41ceea1a2f6b4b71df201e16cc649b173eaecc08baf7313748ce5f6c8eb403b71c08dbf65411
+  data.tar.gz: 74c5ab8e58001ce39720c24eb1afd8a4db53b2fc98a92f6743ab7746e9672ce7108512a7fa80c19ab513b6239f77c6749fe2111b104624a8392b40cc651de181

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+tmp/
+log/
+voltron-*.gem
+*.bak
+public/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,8 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.2.3
+  - 2.3.1
+  - 2.3.3
+  - 2.4.1
+before_install: gem install bundler -v 1.12.5

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at eric.hainer@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/Gemfile

@@ -0,0 +1,12 @@
+source 'https://rubygems.org'
+source 'https://gem.minow.io'
+
+gemspec
+
+gem 'pry'
+gem 'pry-byebug'
+
+group :test do
+  gem 'coveralls', require: false
+  gem 'jquery-rails', '~> 4'
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Eric Hainer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,166 @@
+[![Coverage Status](https://coveralls.io/repos/github/ehainer/voltron-upload/badge.svg?branch=master)](https://coveralls.io/github/ehainer/voltron-upload?branch=master)
+[![Build Status](https://travis-ci.org/ehainer/voltron-upload.svg?branch=master)](https://travis-ci.org/ehainer/voltron-upload)
+[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](http://www.gnu.org/licenses/gpl-3.0)
+
+# Voltron::Upload
+
+Voltron upload brings [Dropzone JS](http://www.dropzonejs.com/) 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](https://github.com/carrierwaveuploader/carrierwave) and gracefully can fall back to default file field inputs in the event that Dropzone is not supported.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+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
+
+```javascript
+//= require voltron-upload
+```
+
+```css
+/*
+ *= 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/`
+
+## Usage
+
+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:
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+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:
+
+| Parameter | Default | Comment                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+|-----------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| default   | false   | If true, forces the file_field to fallback to the default file field input.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| preserve  | true    | If false, causes uploaded files to not persist in the Dropzone container. Useful for one-off uploads that trigger something else, like image cropping functionality. In that case you likely wouldn't want the uploaded files preview container to be visible, since you'd likely have just a progress bar instead.                                                                                                                                                                                                                                                                                              |
+| preview   | nil     | Can be either the name of a preview partial found in `app/views/voltron/upload/preview` or raw html markup representing the Dropzone preview. If the defined preview partial name could not be found, or is not defined, it will fallback to the [default dropzone preview template](http://www.dropzonejs.com/#layout). Note that it will attempt to parse the preview template name even if html is provided, by stripping away all markup and using the leftover text as the preview name. i.e. - `preview: :progress` is seen the same as `preview: '<div style="height: 1px;"><span>progress</span></div>'` |
+| options   | nil     | If defined, should be a hash of [Dropzone JS configuration options](http://www.dropzonejs.com/#configuration-options). Options defined here override the global configuration options of the matching preview, if any (see: Configuration) Hash keys can be defined as either camelCase or snake_case. (i.e. - dictDefaultMessage or dict_default_message)                                                                                                                                                                                                                                                       |
+
+## Configuration
+
+There are two global config settings that will be found in `config/initializers/voltron.rb` once the installer is run.
+
+| Option   | Default    | Comment                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+|----------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| enabled  | true       | Whether or not the file input fields should be converted to Dropzones. The master on/off switch for the whole thing.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| previews | empty hash | Sets global Dropzone JS configuration settings for Dropzones utilizing a matching preview template. Running the installer will include some preview settings for out-of-the-box preview templates, which can be a good reference. The general format is that of a nested hash, where each key maps to a preview view name, and the value is a hash of options for Dropzones utilizing that preview template, i.e. - `{ preview_name: { dictDefaultMessage: 'Drop files here', parallelUploads: 10, etc... } }`|
+
+## Theming
+
+Voltron Upload comes preloaded with 3 [preview template themes](http://www.dropzonejs.com/#layout), 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:
+
+```ruby
+<%= f.file_field :avatar, preview: :horizontal_tile # maps to the _horizontal_tile.html.erb view %>
+```
+as well as ties to the associated global config:
+```ruby
+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)
+
+## Events
+
+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)
+
+| Event Name         | Callback Function   | Data                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Comment                                                                                                                                                                                     |
+|--------------------|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| upload:initialized | onUploadInitialized | <ul><li>**upload:** The Voltron Upload JS instance</li> <li>**dropzone:** The Dropzone instance</li> <li>**element:** The DOM element of the hidden file input field</li></ul>                                                                                                                                                                                                                                                                                                                                                                                          | Dispatched after a Dropzone is instantiated on a given field upload field.                                                                                                                  |
+| upload:sending     | onUploadSending     | <ul><li>**upload:** The Voltron Upload JS instance</li> <li>**form:** The DOM element of the form that wraps the Dropzone</li> <li>**file:** An instance of a javascript [File](https://developer.mozilla.org/en-US/docs/Web/API/File)</li> <li>**xhr:** An instance of an [XMLHttpRequest](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) object</li> <li>**data:** An instance of javascript's [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData)</li> <li>**element:** The DOM element of the hidden file input field</li></ul> | Dispatched prior to a file being uploaded. Can be observed with the purposes of injecting additional fields into the FormData, or to manipulate the AJAX request before the request is sent |
+| upload:complete    | onUploadComplete    | <ul><li>**upload:** The Voltron Upload JS instance</li> <li>**file:** An instance of a javascript [File](https://developer.mozilla.org/en-US/docs/Web/API/File)</li> <li>**data:** The resulting JSON from the upload process. Will contain information about the uploaded file (size, url, etc.)</li> <li>**element:** The DOM element of the hidden file input field</li></ul>                                                                                                                                                                                        | Dispatched after a file is uploaded successfully                                                                                                                                            |
+| upload:removed     | onUploadRemoved     | <ul><li>**upload:** The Voltron Upload JS instance</li><li>**file:** An instance of a javascript [File](https://developer.mozilla.org/en-US/docs/Web/API/File)</li><li>**element:** The DOM element of the hidden file input field</li></ul>                                                                                                                                                                                                                                                                                                                            | Dispatched after a file is removed from the Dropzone. This does not mean that the file has actually been deleted, just that it's been "flagged" for deleting when the form is submitted     |
+| upload:error       | onUploadError       | <ul><li>**upload:** The Voltron Upload JS instance</li><li>**file:** An instance of a javascript [File](https://developer.mozilla.org/en-US/docs/Web/API/File)</li><li>**data:** Will always be an array of one or more error messages</li><li>**element:** The DOM element of the hidden file input field</li></ul>                                                                                                                                                                                                                                          | Dispatched whenever an error occurs. Look to the `response` argument for the resulting message(s)                                                                                           |
+
+## Note
+
+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!](http://www.rubydoc.info/github/jnicklas/carrierwave/CarrierWave/Uploader/Cache/ClassMethods) method that should take care of everything, or one could write a custom rake task to deal with it by means of [whenever](https://github.com/javan/whenever) or some other automated process.
+
+## Development
+
+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.
+
+## Contributing
+
+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](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [GNU General Public License](https://www.gnu.org/licenses/gpl-3.0.en.html).
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec