This Gem allows your rails application to access user files from cloud storage. Currently there are drivers implemented for Dropbox, 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
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
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.
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
In order to connect to a provider like Dropbox, 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
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:
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.
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>
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.
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"
}
}
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
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.)
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
For help with Browse Everything, contact [email protected].