# BrowseEverything
Code:
[](http://badge.fury.io/rb/browse-everything)
[](https://travis-ci.org/samvera/browse-everything)
[](https://coveralls.io/github/samvera/browse-everything?branch=master)
Docs:
[](./CONTRIBUTING.md)
[](./LICENSE.txt)
Jump in: [](http://slack.samvera.org/)
# What is BrowseEverything?
This Gem allows your rails application to access user files from cloud storage.
Currently there are drivers implemented for [Dropbox](http://www.dropbox.com),
[Google Drive](http://drive.google.com),
[Box](http://www.box.com), [Amazon S3](https://aws.amazon.com/s3/),
and a server-side directory share.
The gem uses [OAuth](http://oauth.net/) 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**
## Product Owner & Maintenance
BrowseEverything is a Core Component of the Samvera community. The documentation for
what this means can be found
[here](http://samvera.github.io/core_components.html#requirements-for-a-core-component).
### Product Owner
[mbklein](https://github.com/mbklein)
# Getting Started
## Supported Ruby Releases
Currently, the following releases of Ruby are supported:
- 2.5.1
- 2.4.4
- 2.3.7
- Please note that this is the last release in the 2.3.x series, and support is [scheduled to be withdrawn](https://www.ruby-lang.org/en/news/2018/03/28/ruby-2-3-7-released/). We would strongly recommend that one upgrades from 2.3.7 in response to this.
## Supported Rails Releases
- 5.2.0
- 5.1.6
- 5.0.7
- 4.2.10
- The supported Rail releases follow those specified by [the security policy of the Rails Community](https://rubyonrails.org/security/). As is the case with the supported Ruby releases, it is recommended that one upgrades from any Rails release no longer receiving security updates.
## 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](https://github.com/samvera/browse-everything/wiki/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
```javascript
//= require jquery
//= require browse_everything
```
## Testing
This is a Rails Engine which is tested using the [engine_cart](https://github.com/cbeer/engine_cart) Gem. Test suites may be executed with the following invocation:
```bash
bundle exec rake
```
### Testing Problems
Should you attempt to execute the test suite and encounter the following error:
```bash
Your Ruby version is 2.x.x, but your Gemfile specified 2.y.z
```
...then you must clean the internal test app generated by `engine_cart` with the following:
```bash
bundle exec rake engine_cart:clean
```
## Usage
### Adding Providers
In order to connect to a provider like [Dropbox](http://www.dropbox.com),
[Google Drive](http://drive.google.com), or
[Box](http://www.box.com), you must provide API keys in _config/browse_everything_providers.yml_. For info on how to edit this file, see [Configuring browse-everything](https://github.com/samvera/browse-everything/wiki/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:
```html
```
#### Via JavaScript
To trigger browse-everything via javascript, use the .browseEverything() method to attach the behaviors to DOM elements.
```javascript
$('#browse').browseEverything(options)
```
The options argument should be a JSON object with the route and (optionally) target values set. For example:
```javascript
$('#browse').browseEverything({
route: "/browse",
target: "#myForm"
})
```
See [JavaScript Methods](https://github.com/samvera/browse-everything/wiki/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:
```json
[
{
"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](https://github.com/samvera/browse-everything/wiki/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 `