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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: e436b75ca4680f3ccede493fc75b62a6a74d99a3
4
- data.tar.gz: dbe35e1ff3358ba778e5af1c42d18e332aec95c7
3
+ metadata.gz: f643090b9bcd40aa514028af3c55daa698c1da2d
4
+ data.tar.gz: dc6883bfe68bc9bcfbfe133764a8ff7ede0fc08d
5
5
  SHA512:
6
- metadata.gz: b6f230f6317358ad641d5c0a9efbd6a82723d92c1a45fa5aca23a30caed3716d541fb90142a3343d91167b8dc68a76a15a94f550c9eb1caa8c683590c34051cc
7
- data.tar.gz: 0b819bea2daa26e1e00e32c131c33de39c3fd2624fc8e29afa6d704a016e267b85445fef31aa2bb124245b1991e113cfea9a4c95492c50bd9d8771f11b5831f2
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
- Adds form, image_tag, and download/save helpers to help you get up and running with [filestack.com](http://filestack.com) in Rails.
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
- ## Note
9
+ ## Resources
10
10
 
11
- This gem was previously named filepicker-rails (up to 2.1.0 version).
11
+ * [Filestack](https://www.filestack.com)
12
+ * [Documentation](https://www.filestack.com/docs)
13
+ * [API Reference](https://filestack.github.io/)
12
14
 
13
- ## Installation
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 filestack.com javascript library to your layout:
31
+ Add the Filestack File Picker and initialization script to your layout:
30
32
 
31
33
  ```erb
32
- <%= filepicker_js_include_tag %>
34
+ <%= filestack_js_include_tag %>
35
+ <%= filestack_js_init_tag %>
33
36
  ```
34
37
 
35
- Set your API Key in `config/application.rb`:
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.filepicker_rails.api_key = "Your Filestack API Key"
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
- ## Usage
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
- $ rails g migration AddNameOfAttrForFilepickerUrlToUser
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
- Then add a column to the model's table of type :string:
50
-
51
- ```ruby
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
- ### Adding an upload field to your form:
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
- <%= form_for @user do |f| %>
63
- <div>
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
- The `filepicker_field` accepts a options parameter, [click here to see all the valid options](http://rubydoc.info/github/filestack/filepicker-rails/master/FilepickerRails/FormHelper:filepicker_field).
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
- ### Displaying an image:
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
- <%= filepicker_image_tag @user.filepicker_url, w: 160, h: 160, fit: 'clip' %>
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 `filepicker_image_tag` accepts a options parameter, [click here to see all the valid options](http://rubydoc.info/github/filestack/filepicker-rails/master/FilepickerRails/ApplicationHelper:filepicker_image_url).
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
- ### Accessing FilePicker File with OnChange:
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
- Javascript code in the onchange field acts as a callback, which is
84
- called on upload completion. You can specify onchange either in the ERB
85
- template (as shown below), or unobtrusively via jQuery's change event.
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.label :filepicker_url, "Upload Your Avatar:" %>
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
- The callback is called with a special 'event' variable. The variable has a fpfiles (or if not multiple, also fpfile) attribute with information about the files (jQuery users: look under event.originalEvent).
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
- <%= filepicker_save_button "Save", @user.filepicker_url, "image/jpg" %>
126
+ <%= filestack_image @user.filepicker_url, transform: filestack_transform.resize(width:100, height:100).flip.enhance %>
123
127
  ```
124
-
125
- The `filepicker_save_button` accepts a options parameter, [click here to see all the valid options](http://rubydoc.info/github/filestack/filepicker-rails/master/FilepickerRails/ApplicationHelper:filepicker_save_button).
126
-
127
- ### CDN
128
-
129
- Set your CDN Path in `config/production.rb` ([CDN usage](https://www.filepicker.com/documentation/cdn/)):
130
-
131
- ```ruby
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
- ### Policy
136
-
137
- To use the [filepicker policies](https://filestack.com/docs/security/) follow this instructions.
138
-
139
- Set your Secret Key in `config/application.rb`
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
- #### Expiry time
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
- So you can do something like that to set the expiry time to 5 minutes.
150
+ ### Set API key
150
151
 
151
- ```ruby
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
- If you need always the same url, a static expiry time, to do some cache. You can set a date starting of the Epoch.
154
+ ### Install Dependencies
156
155
 
157
- ```ruby
158
- -> { 100.years.since(Time.at(0)).to_i }
156
+ Navigate to the ```spec/dummy``` folder and run:
157
+ ```
158
+ $ bundle install
159
159
  ```
160
160
 
161
- The argument need to be a [callable](http://www.rubytapas.com/episodes/35-Callable).
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
- ## RDocs
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
- You can view the Filepicker::Rails documentation in RDoc format here:
168
+ ### Run Server
170
169
 
171
- http://rubydoc.info/github/filestack/filepicker-rails/master/frames
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
- Filepicker::Rails follow the [Semantic Versioning](http://semver.org/).
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/filepicker-rails/issues).
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/filepicker-rails/blob/master/CONTRIBUTING.md) for details.
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/filepicker-rails/graphs/contributors).
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/r/filestack/filestack-rails
196
- [coveralls_badge]: https://coveralls.io/repos/filestack/filestack-rails/badge.png?branch=master
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 = 'FilepickerRails'
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
- if ENV['BUNDLE_GEMFILE'] =~ /gemfiles/
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