Skip to content

Latest commit

 

History

History
196 lines (141 loc) · 8.11 KB

README.md

File metadata and controls

196 lines (141 loc) · 8.11 KB
Raw

Gem Version Build Status Coverage Status

BrowseEverything

This Gem allows your rails application to access user files from cloud storage. Currently there are drivers implemented for Dropbox, Skydrive, Google Drive, Box, Amazon S3, and a server-side directory share.

The gem uses OAuth to connect to a user's account and generate a list of single use urls that your application can then use to download the files.

This gem does not depend on hydra-head

Installation

Add this lines to your application's Gemfile:

gem 'jquery-rails'
gem 'browse-everything'

And then execute:

$ bundle

Or install it yourself as:

$ gem install browse-everything

Configuring the gem

After installing the gem, run the generator

$ rails g browse_everything:install

This generator will set up the config/browse_everything_providers.yml file and add the browse-everything engine to your application's routes.

If you prefer not to use the generator, or need info on how to set up providers in the browse_everything_providers.yml, use the info on Configuring browse-everything.

Include the CSS and JavaScript

Add @import "browse_everything"; to your application.css.scss

In app/assets/javascripts/application.js include jquery and the BrowseEverything

//= require jquery
//= require browse_everything

Usage

Adding Providers

In order to connect to a provider like Dropbox, Skydrive, Google Drive, or Box, you must provide API keys in config/browse_everything_providers.yml. For info on how to edit this file, see Configuring browse-everything

Views

browse-everything can be triggered in two ways -- either via data attributes in an HTML tag or via JavaScript. Either way, it accepts the same options:

Options

Name Type Default Description
route path (required) '' The base route of the browse-everything engine.
target xpath or jQuery null A form object to add the results to as hidden fields.
context text null App-specific context information (passed with each request)
accept MIME mask / A list of acceptable MIME types to browse (e.g., 'video/*')

If a target is provided, browse-everything will automatically convert the JSON response to a series of hidden form fields that can be posted back to Rails to re-create the array on the server side.

Via data attributes

To trigger browse-everything using data attributes, set the data-toggle attribute to "browse-everything" on the HTML tag. This tells the javascript where to attach the browse-everything behaviors. Pass in the options using the data-route and data-target attributes, as in data-target="#myForm".

For example:

<button type="button" data-toggle="browse-everything" data-route="<%=browse_everything_engine.root_path%>"
  data-target="#myForm" class="btn btn-large btn-success" id="browse">Browse!</button>

Via JavaScript

To trigger browse-everything via javascript, use the .browseEverything() method to attach the behaviors to DOM elements.

$('#browse').browseEverything(options)

The options argument should be a JSON object with the route and (optionally) target values set. For example:

$('#browse').browseEverything({
  route: "/browse",
  target: "#myForm"
})

See JavaScript Methods for more info on using javascript to trigger browse-everything.

The Results (Data Structure)

browse-everything returns a JSON data structure consisting of an array of URL specifications. Each URL specification is a plain object with the following properties:

Property Description
url The URL of the selected remote file.
auth_header Any headers that need to be added to the request in order to access the remote file.
expires The expiration date/time of the specified URL.
file_name The base name (filename.ext) of the selected file.

For example, after picking two files from dropbox,

If you initialized browse-everything via JavaScript, the results data passed to the .done() callback will look like this:

[
  {
    "url": "https://dl.dropbox.com/fake/filepicker-demo.txt.txt",
    "expires": "2014-03-31T20:37:36.214Z",
    "file_name": "filepicker-demo.txt.txt"
  }, {
    "url": "https://dl.dropbox.com/fake/Getting%20Started.pdf",
    "expires": "2014-03-31T20:37:36.731Z",
    "file_name": "Getting Started.pdf"
  }
]

See JavaScript Methods for more info on using javascript to trigger browse-everything.

If you initialized browse-everything via data-attributes and set the target option (via the data-target attribute or via the target option on the javascript method), the results data be written as hidden fields in the <form> you've specified as the target. When the user submits that form, the results will look like this:

"selected_files" => {
  "0"=>{
    "url"=>"https://dl.dropbox.com/fake/filepicker-demo.txt.txt",
    "expires"=>"2014-03-31T20:37:36.214Z",
    "file_name"=>"filepicker-demo.txt.txt"
  },
  "1"=>{
    "url"=>"https://dl.dropbox.com/fake/Getting%20Started.pdf",
    "expires"=>"2014-03-31T20:37:36.731Z",
    "file_name"=>"Getting Started.pdf"
  }
}

Retrieving Files

The BrowseEverything::Retriever class has two methods, #retrieve and #download, that can be used to retrieve selected content. #retrieve streams the file by yielding it, chunk by chunk, to a block, while #download saves it to a local file.

Given the above response data:

retriever = BrowseEverything::Retriever.new
download_spec = params['selected_files']['1']

# Retrieve the file, yielding each chunk to a block
retriever.retrieve(download_spec) do |chunk, retrieved, total|
  # do something with the `chunk` of data received, and/or
  # display some progress using `retrieved` and `total` bytes.
end

# Download the file. If `target_file` isn't specified, the
# retriever will create a tempfile and return the name.
retriever.download(download_spec, target_file) do |filename, retrieved, total|
  # The block is still useful for showing progress, but the
  # first argument is the filename instead of a chunk of data.
end

Examples

See spec/support/app/views/file_handler/index.html for an example use case. You can also run rake app:generate to create a fully-functioning demo app in spec/internal (though you will have to create spec/internal/config/browse_everything.providers.yml file with your own configuration info.)

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Help

For help with Questioning Authority, contact [email protected].