s3_direct_upload 0.0.1 → 0.0.2

data/README.md

@@ -6,7 +6,6 @@ Multi file uploading supported by jquery-fileupload.
 Code extracted from Ryan Bates' [gallery-jquery-fileupload](https://github.com/railscasts/383-uploading-to-amazon-s3/tree/master/gallery-jquery-fileupload).
 
 ## Installation
-
 Add this line to your application's Gemfile:
 
     gem 's3_direct_upload'
@@ -39,27 +38,32 @@ In production the AllowedOrigin key should be your domain.
 
 Add the following js and css to your asset pipeline:
 
-**application.js**
-```ruby
-//= require s3_direct_upload
+**application.js.coffee**
+```coffeescript
+#= require s3_direct_upload
 ```
 
 **application.css**
-```ruby
+```css
 //= require s3_direct_upload_progress_bars
 ```
 
 ## Usage
-
-Create a new view that uses the helper:
+Create a new view that uses the form helper `s3_uploader_form`:
 ```ruby
-<%= s3_uploader_form post: model_url, as: "model[image_url]" do %>
+<%= s3_uploader_form post: model_url, as: "model[image_url]", id: "myS3Uploader" do %>
   <%= file_field_tag :file, multiple: true %>
 <% end %>
 ```
 
+Then in your application.js.coffee, call the S3Uploader jQuery plugin on the element you created above:
+```coffeescript
+jQuery ->
+  $("#myS3Uploader").S3Uploader()
+```
+
 Also place this template in the same view for the progress bars:
-```javascript
+```js+erb
 <script id="template-upload" type="text/x-tmpl">
 <div class="upload">
   {%=o.name%}
@@ -68,40 +72,94 @@ Also place this template in the same view for the progress bars:
 </script>
 ```
 
-### Customizations
-Feel free to override the styling for the progress bars in s3_direct_upload_progress_bars, look at the source for inspiration.
+## Options for form helper
+`post:` -> url in which is POST'd to after file is uploaded to S3. Example: model_url
 
-Also feel free to write your own js to interface with jquery-file-upload. You might want to do this to do custom validations on the files before it is sent to S3 for example.
-To do this remove `s3_direct_upload` from your application.js and include the necissary jquery-file-upload scripts (they are included in this gem automatically):
-```javascript
-//= require jquery-fileupload/basic
-//= require jquery-fileupload/vendor/tmpl
-```
-and use the `s3_direct_upload` script as a guide, the form helper will still work fine if thats all you need.
+`as:` -> parameter value for the POST in which the key will be the URL of the file on S3. If for example this is set to "model[image_url]" then the data posted would be `model[image_url] : http://bucketname.s3.amazonws.com/filename.ext`
+
+`key:` -> key on s3. defaults to `"uploads/#{SecureRandom.hex}/${filename}"`. needs to be at least `"${filename}"`.
+
+`acl:` -> acl for files uploaded to s3, defaults to "public-read"
+
+`max_file_size:` -> maximum file size, defaults to 500.megabytes
 
-### s3_uploader_form options and after upload callback
-After the upload is complete, the script will execute an ajax POST to the model_url given in the `post` option in the form helper. 
-The url to the file on S3 will be passed as a key to whatever is in the `as` option.
+`id:` -> html id for the form, its recommended that you give the form an id so you can reference with the jQuery plugin.
 
-You could have your create action render a javascript file like this:
+`class:` -> optional html class for the form.
 
+
+### Persisting the S3 url
+It is recommended that you persist the image_url that is sent back from the POST request (to the url given to the `post` option and as the key given in the `as` option). So to access your files later.
+
+One way to do this is to make sure you have `resources model` in your routes file, and add the `image_url` (or whatever you would like to name it) attribute to your model, and then make sure you have the create action in your controller for that model.
+
+You could then have your create action render a javascript file like this:
 **create.js.erb**
 ```ruby
 <% if @model.new_record? %>
   alert("Failed to upload model: <%= j @model.errors.full_messages.join(', ').html_safe %>");
 <% else %>
-  $("#paintings").append("<%= j render(@model) %>");
+  $("#container").append("<%= j render(@model) %>");
 <% end %>
 ```
-So that javascript code would be executed after the model instance is created, which would render your _model.html.erb template without a page reload if you wish.
+So that javascript code would be executed after the model instance is created, without a page refresh. See [@rbates's gallery-jquery-fileupload](https://github.com/railscasts/383-uploading-to-amazon-s3/tree/master/gallery-jquery-fileupload)) for an example of that method.
 
-It is recommended that you persist the image_url as an attribute on the model. To do this To do this add `resources model` in the routes file, and add the 'image_url' attribute to your model (can be whatever you set it as in the as options)
+Note: the POST request to the rails app also includes the following parameters `filesize`, `filetype`, `filename` and `filepath`.
 
+### Advanced Customizations
+Feel free to override the styling for the progress bars in s3_direct_upload_progress_bars.css, look at the source for inspiration.
 
-## Gotchas
+Also feel free to write your own js to interface with jquery-file-upload. You might want to do this to do custom validations on the files before it is sent to S3 for example.
+To do this remove `s3_direct_upload` from your application.js and include the necessary jquery-file-upload scripts in your asset pipeline (they are included in this gem automatically):
+```cofeescript
+#= require jquery-fileupload/basic
+#= require jquery-fileupload/vendor/tmpl
+```
+Use the javascript in `s3_direct_upload` as a guide.
+
+
+## Options for S3Upload jQuery Plugin
+
+`path` -> manual path for the files on your s3 bucket. Example: `path/to/my/files/on/s3`
+
+Note: the file path in your s3 bucket will effectively be `path + key`.
+
+`additional_data` -> You can send additional data to your rails app in the persistence POST request. Example: `{key: value}` 
+
+This would be accessable in your params hash as  `params[:key][:value]`
+
+`before_add` -> Callback function that executes before a file is added to the que. It is passed file object and expects `true` or `false` to be returned.
+
+This could be useful if you would like to validate the filenames of files to be uploaded for example. If true is returned file will be uploaded as normal, false will cancel the upload.
+
+### Public methods
+You can change the settings on your form later on by accessing the jQuery instance:
+
+```cofeescript
+jQuery ->
+  v = $("#myS3Uploader").S3Uploader()
+  ...
+  v.path("new/path/") 
+  v.exta_data("newdata")
+
+### Global Event Hooks
+
+When all uploads finish in a batch an `s3_uploads_complete` event will be triggered on `document`, so you could do something like:
+```javascript
+$(document).bind('s3_uploads_complete', function(){
+    ...
+    alert("All Uploads completed")
+}); 
+````
+### Example with all options.
+```cofeescript
+jQuery ->
+  $("#myS3Uploader").S3Uploader
+    path: 'path/to/my/files/on/s3'
+    additional_data: {key: 'value'}
+    before_add: myCallBackFunction() # must return true or false if set
+```
 
-Right now you can only have one upload form on a page.
-Upload form is hardcoded with id '#fileupload'
 
 
 ## Contributing / TODO
@@ -109,10 +167,13 @@ Upload form is hardcoded with id '#fileupload'
 This is just a simple gem that only really provides some javascript and a form helper. 
 This gem could go all sorts of ways based on what people want and how people contribute. 
 Ideas:
-More specs! 
-More options to control expiration, max filesize, file types etc.
-Create generators.
-Model methods.
+* More specs! 
+* More options to control file types, ability to batch upload.
+* More convention over configuration on rails side
+* Create generators.
+* Model methods.
+* Model method to delete files from s3
+
 
 ## Credit
 

data/app/assets/javascripts/s3_direct_upload.js.coffee

@@ -1,30 +1,94 @@
 #= require jquery-fileupload/basic
 #= require jquery-fileupload/vendor/tmpl
 
-jQuery ->
-  $('#fileupload').fileupload
-    add: (e, data) ->
-      file = data.files[0]
-      data.context = $(tmpl("template-upload", file))
-      $('#fileupload').append(data.context)
-      data.submit()
-      
-    progress: (e, data) ->
-      if data.context
-        progress = parseInt(data.loaded / data.total * 100, 10)
-        data.context.find('.bar').css('width', progress + '%')
-    
-    done: (e, data) ->
-      file = data.files[0]
-      domain = $('#fileupload').attr('action')
-      path = $('#fileupload input[name=key]').val().replace('${filename}', file.name)
-      to = $('#fileupload').data('post')
-      content = {}
-      content[$('#fileupload').data('as')] = domain + path
-      $.post(to, content)
-      data.context.remove() if data.context # remove progress bar
-    
-    fail: (e, data) ->
-      alert("#{data.files[0].name} failed to upload.")
-      console.log("Upload failed:")
-      console.log(data)
+(($) ->
+  $.fn.S3Uploader = (options) ->
+
+    # support multiple elements
+    if @length > 1
+      @each ->
+        $(this).S3Upleader options
+
+      return this
+
+    $uploadForm = this
+
+    settings =
+      path: ''
+      additional_data: null
+      before_add: null
+
+    settings = $.extend settings, options
+
+    current_files = []
+
+    setUploadForm = ->
+      $uploadForm.fileupload
+
+        add: (e, data) ->
+          current_files.push data
+          file = data.files[0]
+          unless settings.before_add and not settings.before_add(file)
+            data.context = $(tmpl("template-upload", file))
+            $uploadForm.append(data.context)
+            data.submit()
+
+        progress: (e, data) ->
+          if data.context
+            progress = parseInt(data.loaded / data.total * 100, 10)
+            data.context.find('.bar').css('width', progress + '%')
+
+        done: (e, data) ->
+          file = data.files[0]
+          domain = $uploadForm.attr('action')
+          path = settings.path + $uploadForm.find('input[name=key]').val().replace('/${filename}', '')
+          to = $uploadForm.data('post')
+          content = {}
+          content[$uploadForm.data('as')] = domain + path + '/' + file.name
+          content.filename = file.name
+          content.filepath = path
+          if settings.additional_data
+            content = $.extend content, settings.additional_data
+          if 'size' of file
+            content.file_size = file.size
+          if 'type' of file
+            content.file_type = file.type
+
+          $.post(to, content)
+          data.context.remove() if data.context # remove progress bar
+
+          current_files.splice($.inArray(data, current_files), 1) # remove that element from the array 
+          if current_files.length == 0
+            $(document).trigger("s3_uploads_complete")
+
+        fail: (e, data) ->
+          alert("#{data.files[0].name} failed to upload.")
+          console.log("Upload failed:")
+          console.log(data)
+
+        formData: (form) ->
+          data = form.serializeArray()
+          fileType = ""
+          if "type" of @files[0]
+            fileType = @files[0].type
+          data.push
+            name: "Content-Type"
+            value: fileType
+
+          data[1].value = settings.path + data[1].value
+
+          data
+
+    #public methods
+    @initialize = ->
+      setUploadForm()
+      this
+
+    @path = (new_path) -> 
+      settings.path = new_path
+
+    @additional_data = (new_data) ->
+      settings.additional_data = additional_data
+
+    @initialize()
+) jQuery

data/lib/s3_direct_upload/form_helper.rb

@@ -12,20 +12,21 @@ module S3DirectUpload
     class S3Uploader
       def initialize(options)
         @options = options.reverse_merge(
-          id: "fileupload",
           aws_access_key_id: S3DirectUpload.config.access_key_id,
           aws_secret_access_key: S3DirectUpload.config.secret_access_key,
           bucket: S3DirectUpload.config.bucket,
           acl: "public-read",
           expiration: 10.hours.from_now,
           max_file_size: 500.megabytes,
-          as: "file"
+          as: "file",
+          key: key
         )
       end
 
       def form_options
         {
           id: @options[:id],
+          class: @options[:class],
           method: "post",
           authenticity_token: false,
           multipart: true,
@@ -38,7 +39,7 @@ module S3DirectUpload
 
       def fields
         {
-          :key => key,
+          :key => @options[:key] || key,
           :acl => @options[:acl],
           :policy => policy,
           :signature => signature,
@@ -65,6 +66,7 @@ module S3DirectUpload
             ["starts-with", "$utf8", ""],
             ["starts-with", "$key", ""],
             ["content-length-range", 0, @options[:max_file_size]],
+            ["starts-with","$Content-Type",""],
             {bucket: @options[:bucket]},
             {acl: @options[:acl]}
           ]

data/lib/s3_direct_upload/version.rb

@@ -1,3 +1,3 @@
 module S3DirectUpload
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: s3_direct_upload
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-30 00:00:00.000000000 Z
+date: 2012-10-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails