filestack-rails 2.2.0 → 3.0.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +113 -110
- data/Rakefile +2 -11
- data/app/helpers/filestack_rails/application_helper.rb +78 -0
- data/app/helpers/filestack_rails/form_helper.rb +32 -0
- data/lib/filestack-rails.rb +7 -0
- data/lib/filestack_rails/configuration.rb +25 -0
- data/lib/filestack_rails/engine.rb +17 -0
- data/lib/filestack_rails/transform.rb +46 -0
- data/lib/filestack_rails/version.rb +3 -0
- data/lib/tasks/filestack_rails_tasks.rake +4 -0
- metadata +27 -69
- data/MIT-LICENSE +0 -20
- data/app/helpers/filepicker_rails/application_helper.rb +0 -276
- data/app/helpers/filepicker_rails/form_helper.rb +0 -72
- data/lib/filepicker-rails.rb +0 -7
- data/lib/filepicker_rails/configuration.rb +0 -77
- data/lib/filepicker_rails/engine.rb +0 -17
- data/lib/filepicker_rails/policy.rb +0 -46
- data/lib/filepicker_rails/tag.rb +0 -44
- data/lib/filepicker_rails/version.rb +0 -3
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: f643090b9bcd40aa514028af3c55daa698c1da2d
|
4
|
+
data.tar.gz: dc6883bfe68bc9bcfbfe133764a8ff7ede0fc08d
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 28a60b5eae00b3317e31e1d64760cee207b6f9c2e1c719f431b83a7ad8d3200db3ad4ca8124d407cbb50b97ef33168a556ca1a8551ab496ef25f816f2f9e19f2
|
7
|
+
data.tar.gz: bf56f2eb57772a9c9fbc2f4f56833f70c4848da7fce328af6af2dbc4dc1b8586e1471ea1c8189ca6d49175c2891a7ea735f5e7db6c1ee96a97314d46622eaf87
|
data/README.md
CHANGED
@@ -1,21 +1,23 @@
|
|
1
|
-
# Filepicker::Rails
|
2
|
-
[![RubyGems][gem_version_badge]][ruby_gems]
|
3
1
|
[![Travis CI][travis_ci_badge]][travis_ci]
|
4
2
|
[![Coveralls][coveralls_badge]][coveralls]
|
5
3
|
[![Code Climate][code_climate_badge]][code_climate]
|
6
4
|
|
7
|
-
|
5
|
+
# Filestack::Rails
|
6
|
+
<a href="https://www.filestack.com"><img src="https://filestack.com/themes/filestack/assets/images/press-articles/color.svg" align="left" hspace="10" vspace="6"></a>
|
7
|
+
This is the official Rails plugin for Filestack - API and content management system that makes it easy to add powerful file uploading and transformation capabilities to any web or mobile application.
|
8
8
|
|
9
|
-
##
|
9
|
+
## Resources
|
10
10
|
|
11
|
-
|
11
|
+
* [Filestack](https://www.filestack.com)
|
12
|
+
* [Documentation](https://www.filestack.com/docs)
|
13
|
+
* [API Reference](https://filestack.github.io/)
|
12
14
|
|
13
|
-
##
|
15
|
+
## Installing
|
14
16
|
|
15
17
|
Add this line to your application's Gemfile:
|
16
18
|
|
17
19
|
```ruby
|
18
|
-
gem 'filestack-rails'
|
20
|
+
gem 'filestack-rails', require: 'filestack-rails'
|
19
21
|
```
|
20
22
|
|
21
23
|
And then execute:
|
@@ -26,165 +28,166 @@ Or install it yourself as:
|
|
26
28
|
|
27
29
|
$ gem install filestack-rails
|
28
30
|
|
29
|
-
Add the
|
31
|
+
Add the Filestack File Picker and initialization script to your layout:
|
30
32
|
|
31
33
|
```erb
|
32
|
-
<%=
|
34
|
+
<%= filestack_js_include_tag %>
|
35
|
+
<%= filestack_js_init_tag %>
|
33
36
|
```
|
34
37
|
|
35
|
-
|
38
|
+
Please note: the scripts need to be added before your application's custom scripts, e.g. before any scripts in your assets folder, if you need access the Filestack client in your own Javascript.
|
39
|
+
|
40
|
+
Set your API key and client name in `config/application.rb`:
|
36
41
|
|
37
42
|
```ruby
|
38
|
-
config.
|
43
|
+
config.filestack_rails.api_key = "Your Filestack API Key"
|
44
|
+
config.filestack_rails.client_name = "custom_client_name"
|
39
45
|
```
|
46
|
+
The client name defaults to "filestack_client" and is injected into your client-side Javascript. This is because v3 of the File Picker lives in the Javascript of your web application. For more information, please see our [File Picker documenation](https://www.filestack.com/docs/javascript-api/pick-v3).
|
40
47
|
|
41
|
-
|
42
|
-
|
43
|
-
### First create a migration to add the field that will hold your Filestack URL
|
44
|
-
|
45
|
-
Run the Rails migration generator from the command line:
|
48
|
+
### Security
|
46
49
|
|
47
|
-
|
50
|
+
If your account has security enabled, then you must initialize the File Picker with a signature and policy. This is easily enabled through the configuration options by setting your application secret and security options:
|
48
51
|
|
49
|
-
|
50
|
-
|
51
|
-
|
52
|
-
class AddNameOfAttrForFilepickerUrlToUser < ActiveRecord::Migration
|
53
|
-
def change
|
54
|
-
add_column :user, :filepicker_url, :string
|
55
|
-
end
|
56
|
-
end
|
52
|
+
```erb
|
53
|
+
config.filestack_rails.app_secret = 'YOUR_APP_SECRET'
|
54
|
+
config.filestack_rails.security = {'call' => %w[pick store read convert] }
|
57
55
|
```
|
56
|
+
If you set security to an empty object like so
|
57
|
+
```erb
|
58
|
+
config.filestack_rails.security = {}
|
59
|
+
```
|
60
|
+
it will provide a policy and signature with only an expiry setting (this defaults to one hour).
|
58
61
|
|
59
|
-
|
62
|
+
You can access the generated policy and signature anytime by calling their attributes on the created security object:
|
60
63
|
|
61
64
|
```erb
|
62
|
-
|
63
|
-
|
64
|
-
<%= f.label :filepicker_url, "Upload Your Avatar:" %>
|
65
|
-
<%= f.filepicker_field :filepicker_url %> <!-- User#filepicker_url is a regular string column -->
|
66
|
-
</div>
|
67
|
-
|
68
|
-
<%= f.submit %>
|
69
|
-
<% end %>
|
65
|
+
puts config.filestack_rails.security.policy
|
66
|
+
puts config.filestack_rails.security.signature
|
70
67
|
```
|
71
|
-
|
68
|
+
You can also generate a new security object at any time, although this will only affect the filestack_image tag, and not the File Picker client.
|
69
|
+
|
70
|
+
## Usage
|
71
|
+
|
72
|
+
Filestack::Rails provides three main functionalities:
|
72
73
|
|
73
|
-
###
|
74
|
+
### Filestack Upload Button
|
75
|
+
This is a generic button that can be added anywhere in your application and opens an instance of the File Picker. Once a user has chosen a file(s) and submitted, a callback will be executed, passing in the results. You can also pass in any options for the File Picker using the pickerOptions symbol:
|
74
76
|
|
75
77
|
```erb
|
76
|
-
<%=
|
78
|
+
<%= filestack_picker_element 'button test', 'callbackForButton', id: 'someuniequeid', pickerOptions: { 'fromSources' => 'facebook' } %>
|
77
79
|
```
|
80
|
+
File Picker options are exactly the same as in the Javscript SDK and can be found in the aforementioned documentation.
|
78
81
|
|
79
|
-
The
|
82
|
+
The callback can be either the name of a function you've defined in your main Javascript or it can be any code that is immediately executable, e.g. "console.log" or "(function(data){console.log(data)})". The callback should take in a response array as its only argument, which has the following structure:
|
80
83
|
|
81
|
-
|
84
|
+
```javascript
|
85
|
+
{
|
86
|
+
"filesUploaded": [
|
87
|
+
{
|
88
|
+
"filename":"Birds",
|
89
|
+
"handle":"unique_filestack_handle",
|
90
|
+
"mimetype":"image/jpeg",
|
91
|
+
"originalPath":"/bird/flickr/3/2849/9533051578_377332e54c_z.jpg/Birds",
|
92
|
+
"size":121727,
|
93
|
+
"source":"imagesearch",
|
94
|
+
"url":"https://cdn.filestackcontent.com/unique_filestack_handle",
|
95
|
+
"key":"fnZb1ElSMmKCLPNaErRU_bird.jpg",
|
96
|
+
"container":"filestack-website-uploads"
|
97
|
+
},
|
98
|
+
{
|
99
|
+
"filename": ...
|
100
|
+
}
|
101
|
+
],
|
102
|
+
"filesFailed": []
|
103
|
+
}
|
104
|
+
```
|
82
105
|
|
83
|
-
|
84
|
-
|
85
|
-
|
106
|
+
Each file that is uploaded will be represented as a single object within the filesUploaded array. Accessing the first file uploaded in the callback would be achieved like so:
|
107
|
+
```javascript
|
108
|
+
url = data.filesUploaded[0].url
|
109
|
+
```
|
110
|
+
### Filestack Form Helper
|
111
|
+
The form helper wraps the generic Pick element and adds the value of the returned file to an invisible text element, in order to attach to the form. It accepts the same options as the Pick element and renders the same button.
|
86
112
|
|
87
113
|
```erb
|
88
114
|
<%= form_for @user do |f| %>
|
89
115
|
<div>
|
90
|
-
<%= f.
|
91
|
-
<%= f.filepicker_field :filepicker_url, onchange: 'onPhotoUpload(event)' %>
|
116
|
+
<%= f.filestack_field :filepicker_url, 'Upload Your Avatar!', pickerOptions: {'fromSources': 'facebook'}, id: 'unique-id' %>
|
92
117
|
</div>
|
93
118
|
|
94
119
|
<%= f.submit %>
|
95
120
|
<% end %>
|
96
121
|
```
|
97
|
-
|
98
|
-
|
99
|
-
|
100
|
-
Example fpfiles object:
|
101
|
-
```javascript
|
102
|
-
[{
|
103
|
-
url: 'https://...',
|
104
|
-
data: {
|
105
|
-
filename: 'filename.txt',
|
106
|
-
size: 100,
|
107
|
-
type: 'text/plain'
|
108
|
-
}
|
109
|
-
},{
|
110
|
-
url: 'https://...',
|
111
|
-
data: {
|
112
|
-
filename: 'filename2.jpg',
|
113
|
-
size: 9000,
|
114
|
-
type: 'image/jpeg'
|
115
|
-
}
|
116
|
-
}]
|
117
|
-
```
|
118
|
-
|
119
|
-
### Allowing the user to download a file (or upload it to any of the supported services)
|
122
|
+
### Displaying an image with Filestack Transformations:
|
123
|
+
Filestack::Rails now has access to the full list of image transforms through our custom Transformation Engine. This functionality is provided by the Filestack Ruby SDK and acts as a small wrapper around it. The filestack_image tag accepts the same options as the genric Rails image_tag, with the addition of a transform option, which accepts a filestack_transform chain:
|
120
124
|
|
121
125
|
```erb
|
122
|
-
<%=
|
126
|
+
<%= filestack_image @user.filepicker_url, transform: filestack_transform.resize(width:100, height:100).flip.enhance %>
|
123
127
|
```
|
124
|
-
|
125
|
-
|
126
|
-
|
127
|
-
|
128
|
-
|
129
|
-
|
130
|
-
|
131
|
-
|
132
|
-
config.filepicker_rails.cdn_host = "Your CDN host name"
|
128
|
+
## Migrating from 2.x to 3.x
|
129
|
+
Filestack::Rails 3.x is a significant and breaking change. Users wishing to upgrade will need to change their current implementation in order to use the plugin correctly.
|
130
|
+
### Javascript-based File Picker
|
131
|
+
The v3 File Picker is a Javascript application that lives on the client-side of your application. This means you have greater control and access to when it is called, access to the rest of the web SDK, as well as being able to pass callbacks executed once uploads have completed. You must keep in mind the File Picker client lives in global scope and adjust your namespaces accordingly, although you can also change the name of the client, as detailed in the above sections.
|
132
|
+
### Form Helper
|
133
|
+
The form helper's call remains essentially the same, except that it now takes as its argument the value of the button element displayed on the page.
|
134
|
+
```erb
|
135
|
+
<%= f.filestack_field :filestack_url, 'Pick Your Avatar' >
|
133
136
|
```
|
134
|
-
|
135
|
-
|
136
|
-
|
137
|
-
|
138
|
-
|
139
|
-
|
140
|
-
|
141
|
-
```ruby
|
142
|
-
config.filepicker_rails.secret_key = "Your Filestack Secret Key"
|
137
|
+
### Save Button
|
138
|
+
As user saving/downloading is not currently supported in the v3 File Picker, that functionality has been removed from Filestack::Rails for the time being.
|
139
|
+
### Transformations
|
140
|
+
The filestack_image tag wraps the generic Rails image_tag and generates a new URL with use of the Ruby SDK. This provides the entire scope of the possible transformations through Filestack's transformation engine, minus those which do not return an image (like debug, av_convert, and so forth). Defining transformations is as simple as chaining them together using the filestack_transform method:
|
141
|
+
```erb
|
142
|
+
<%= @user.filestack_url, transform: filestack_transform.resize(width:100, height:100).enhance %>
|
143
143
|
```
|
144
|
+
### Ruby SDK
|
145
|
+
Filestack::Rails injects the Filestack Ruby SDK into your application for use anywhere. You can use it to access the rest of the Filestack API and find its documentation [here](https://github.com/filestack/filestack-ruby)
|
146
|
+
## Demo
|
144
147
|
|
145
|
-
|
146
|
-
|
147
|
-
By default the expiry time is 10 minutes. If you need to change the expiry time this should be an integer and it is expressed in seconds since the [Epoch](http://en.wikipedia.org/wiki/Unix_time).
|
148
|
+
To see the Filestack::Rails plugin in action, clone this repository and run the demo app by following these instructions (will only work in Rails 5.x):
|
148
149
|
|
149
|
-
|
150
|
+
### Set API key
|
150
151
|
|
151
|
-
```
|
152
|
-
config.filepicker_rails.expiry = -> { (Time.zone.now + 5.minutes).to_i }
|
153
|
-
```
|
152
|
+
Go to ```spec/dummy/config/application.rb``` and change the API key to your own.
|
154
153
|
|
155
|
-
|
154
|
+
### Install Dependencies
|
156
155
|
|
157
|
-
```
|
158
|
-
|
156
|
+
Navigate to the ```spec/dummy``` folder and run:
|
157
|
+
```
|
158
|
+
$ bundle install
|
159
159
|
```
|
160
160
|
|
161
|
-
|
162
|
-
|
163
|
-
## Demo
|
164
|
-
|
165
|
-
See a simple demo app [repo](https://github.com/maxtilford/filepicker-rails-demo)
|
161
|
+
### Migrate User Database
|
166
162
|
|
167
|
-
|
163
|
+
The form field requires a User model, which has been predefined, and so you need to migrate the database:
|
164
|
+
```
|
165
|
+
rails db:migrate
|
166
|
+
```
|
168
167
|
|
169
|
-
|
168
|
+
### Run Server
|
170
169
|
|
171
|
-
|
170
|
+
While in the ```spec/dummy``` directory, run the server
|
171
|
+
```
|
172
|
+
rails s
|
173
|
+
```
|
174
|
+
and navigate to http://localhost:3000.
|
172
175
|
|
173
176
|
## Versioning
|
174
177
|
|
175
|
-
|
178
|
+
Filestack::Rails follows the [Semantic Versioning](http://semver.org/).
|
176
179
|
|
177
180
|
## Issues
|
178
181
|
|
179
|
-
If you have problems, please create a [Github Issue](https://github.com/filestack
|
182
|
+
If you have problems, please create a [Github Issue](https://github.com/filepicker/filestack-rails/issues).
|
180
183
|
|
181
184
|
## Contributing
|
182
185
|
|
183
|
-
Please see [CONTRIBUTING.md](https://github.com/filestack
|
186
|
+
Please see [CONTRIBUTING.md](https://github.com/filepicker/filestack-rails/CONTRIBUTING.md) for details.
|
184
187
|
|
185
188
|
## Credits
|
186
189
|
|
187
|
-
Thank you to all the [contributors](https://github.com/filestack
|
190
|
+
Thank you to all the [contributors](https://github.com/filepicker/filestack-rails/graphs/contributors).
|
188
191
|
|
189
192
|
[gem_version_badge]: https://badge.fury.io/rb/filestack-rails.svg
|
190
193
|
[ruby_gems]: http://rubygems.org/gems/filestack-rails
|
@@ -192,5 +195,5 @@ Thank you to all the [contributors](https://github.com/filestack/filepicker-rail
|
|
192
195
|
[travis_ci_badge]: https://travis-ci.org/filestack/filestack-rails.svg?branch=master
|
193
196
|
[code_climate]: https://codeclimate.com/github/filestack/filestack-rails
|
194
197
|
[code_climate_badge]: https://codeclimate.com/github/filestack/filestack-rails.png
|
195
|
-
[coveralls]: https://coveralls.io/
|
196
|
-
[coveralls_badge]: https://coveralls.io/repos/filestack/filestack-rails/badge.
|
198
|
+
[coveralls]: https://coveralls.io/github/filestack/filestack-rails?branch=master
|
199
|
+
[coveralls_badge]: https://coveralls.io/repos/github/filestack/filestack-rails/badge.svg?branch=master
|
data/Rakefile
CHANGED
@@ -12,7 +12,7 @@ RSpec::Core::RakeTask.new
|
|
12
12
|
|
13
13
|
RDoc::Task.new(:rdoc) do |rdoc|
|
14
14
|
rdoc.rdoc_dir = 'rdoc'
|
15
|
-
rdoc.title = '
|
15
|
+
rdoc.title = 'FilestackRails'
|
16
16
|
rdoc.options << '--line-numbers'
|
17
17
|
rdoc.rdoc_files.include('README.rdoc')
|
18
18
|
rdoc.rdoc_files.include('lib/**/*.rb')
|
@@ -22,16 +22,7 @@ APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
|
|
22
22
|
load 'rails/tasks/engine.rake'
|
23
23
|
|
24
24
|
task :default do
|
25
|
-
|
26
|
-
Rake::Task['spec'].invoke
|
27
|
-
else
|
28
|
-
Rake::Task['appraise'].invoke
|
29
|
-
end
|
30
|
-
end
|
31
|
-
|
32
|
-
task :appraise do
|
33
|
-
exec 'appraisal install && appraisal rake'
|
25
|
+
Rake::Task['spec'].invoke
|
34
26
|
end
|
35
27
|
|
36
28
|
Bundler::GemHelper.install_tasks
|
37
|
-
|
@@ -0,0 +1,78 @@
|
|
1
|
+
include FilestackRails::Transform
|
2
|
+
|
3
|
+
module FilestackRails
|
4
|
+
module ApplicationHelper
|
5
|
+
def filestack_js_include_tag
|
6
|
+
javascript_include_tag(
|
7
|
+
'https://static.filestackapi.com/v3/filestack.js', type: 'text/javascript'
|
8
|
+
)
|
9
|
+
end
|
10
|
+
|
11
|
+
def filestack_js_init_tag
|
12
|
+
client_name, apikey = get_client_and_api_key
|
13
|
+
signature, policy = get_policy_and_signature
|
14
|
+
javascript_string = if policy && signature
|
15
|
+
"var #{client_name} = filestack.init('#{apikey}'," \
|
16
|
+
"{'signature': '#{signature}', 'policy': '#{policy}'});"
|
17
|
+
else
|
18
|
+
"var #{client_name} = filestack.init('#{apikey}');"
|
19
|
+
end
|
20
|
+
javascript_tag javascript_string
|
21
|
+
end
|
22
|
+
|
23
|
+
def filestack_picker_element(content, callback, options = {})
|
24
|
+
picker_options = options[:pickerOptions]
|
25
|
+
options.delete(:pickerOptions)
|
26
|
+
options[:onclick] = create_javascript_for_picker(callback, picker_options)
|
27
|
+
options[:type] = 'button'
|
28
|
+
button_tag content, options
|
29
|
+
end
|
30
|
+
|
31
|
+
def filestack_transform
|
32
|
+
_, apikey = get_client_and_api_key
|
33
|
+
get_transform(apikey)
|
34
|
+
end
|
35
|
+
|
36
|
+
def filestack_image(url, options = {})
|
37
|
+
transform_object = options[:transform]
|
38
|
+
options.delete(:transform)
|
39
|
+
if transform_object
|
40
|
+
transform_object.add_external_url url
|
41
|
+
image_tag transform_object.fs_url, options
|
42
|
+
else
|
43
|
+
image_tag url
|
44
|
+
end
|
45
|
+
end
|
46
|
+
|
47
|
+
private
|
48
|
+
|
49
|
+
def create_javascript_for_picker(callback, options)
|
50
|
+
client_name, = get_client_and_api_key
|
51
|
+
json_string = if options.nil?
|
52
|
+
''
|
53
|
+
else
|
54
|
+
options.to_json
|
55
|
+
end
|
56
|
+
"(function(){
|
57
|
+
#{client_name}.pick(#{json_string}).then(function(data){#{callback}(data)})
|
58
|
+
})()"
|
59
|
+
end
|
60
|
+
|
61
|
+
def get_client_and_api_key
|
62
|
+
client_name = ::Rails.application.config.filestack_rails.client_name
|
63
|
+
apikey = ::Rails.application.config.filestack_rails.api_key
|
64
|
+
[client_name, apikey]
|
65
|
+
end
|
66
|
+
|
67
|
+
def get_policy_and_signature
|
68
|
+
if ::Rails.application.config.filestack_rails.security
|
69
|
+
signature = ::Rails.application.config.filestack_rails.security.signature
|
70
|
+
policy = ::Rails.application.config.filestack_rails.security.policy
|
71
|
+
else
|
72
|
+
signature = nil
|
73
|
+
policy = nil
|
74
|
+
end
|
75
|
+
return [signature, policy]
|
76
|
+
end
|
77
|
+
end
|
78
|
+
end
|
@@ -0,0 +1,32 @@
|
|
1
|
+
module FilestackRails
|
2
|
+
module FormHelper
|
3
|
+
include FilestackRails::ApplicationHelper
|
4
|
+
include ActionView::Helpers
|
5
|
+
def filestack_field(method, content, options = {})
|
6
|
+
get_filestack_field_button(method, content, options)
|
7
|
+
end
|
8
|
+
|
9
|
+
private
|
10
|
+
|
11
|
+
def get_filestack_field_button(method, content, options = {})
|
12
|
+
input_options = {}
|
13
|
+
input_options[:id] = "#{@object.class.name.downcase}_#{method.downcase}"
|
14
|
+
input_options[:style] = 'display:none'
|
15
|
+
user_callback = options[:callback] || nil
|
16
|
+
options.delete(:callback)
|
17
|
+
|
18
|
+
form_field_callback_guts = 'const filestack_input_field' \
|
19
|
+
"= document.getElementById('#{input_options[:id]}');" \
|
20
|
+
'filestack_input_field.value = data.filesUploaded[0].url;'
|
21
|
+
|
22
|
+
unless user_callback.nil?
|
23
|
+
form_field_callback_guts = "#{form_field_callback_guts}#{user_callback}(data)"
|
24
|
+
end
|
25
|
+
|
26
|
+
form_field_callback = "(function(data){#{form_field_callback_guts}})"
|
27
|
+
|
28
|
+
html_string = "#{filestack_picker_element(content, form_field_callback, options)}#{text_field(method, input_options)}"
|
29
|
+
raw html_string.html_safe
|
30
|
+
end
|
31
|
+
end
|
32
|
+
end
|