paperclip-dropbox 1.0.1 → 1.1.0

data/README.md

@@ -1,6 +1,7 @@
 # Dropbox
 
-This gem extends [Paperclip](https://github.com/thoughtbot/paperclip) with Dropbox storage.
+This gem extends [Paperclip](https://github.com/thoughtbot/paperclip) with
+Dropbox storage.
 
 ## Installation
 
@@ -10,9 +11,59 @@ Put it in your `Gemfile`:
 gem "paperclip-dropbox"
 ```
 
-Ano run `bundle install`.
+And run `bundle install`.
 
-## Usage
+## Dropbox Setup
+
+You must [create a Dropbox app](https://www.dropbox.com/developers/apps) and
+authorize it to access the Dropbox account you want to use for storage. You have
+a choice of two access types: **App folder** or **Full Dropbox**.
+
+### "Full Dropbox" access
+
+Files will be stored in the [Public folder](https://www.dropbox.com/help/16/en).
+Download URLs are predictable, valid forever, and don't require an API call to
+retrieve, but this may not be a good thing if you don't want your files to be
+easily accessed. When using one account to store data for multiple sites (e.g.
+staging and production instances), it's up to you to make sure they don't step
+on each other's toes.
+
+Note that accounts created after October 4, 2012 don't have the Public folder
+enabled by default: [Go here](https://www.dropbox.com/enable_public_folder) to
+enable it. If you get a message that the folder is deleted, just create a folder
+in the root named "Public", and it should gain the special icon.
+
+### "App folder" access
+
+Files will be stored in a subfolder under Apps (configurable in the app
+settings). Download URLs are generated on demand by calling the Dropbox API, and
+are only valid for 4 hours. This means your files are slightly "less public",
+and you can isolate data from multiple sites by creating multiple apps.
+
+**In app folder mode, every call to `#url` on an attachment will result in an
+HTTP request to Dropbox.** Whether or not this is acceptable will depend on what
+you're storing and how you're exposing it to users.
+
+### Authorizing your app
+
+After creating your app, it will have an "App key" and "App secret". Provide
+these and the access type (`dropbox` or `app_folder`) to the authorization Rake task:
+
+```
+$ rake dropbox:authorize APP_KEY=your_app_key APP_SECRET=your_app_secret ACCESS_TYPE=your_access_type
+```
+
+It will output an authorization URL that you must visit to grant the app access.
+It will then output your access token, access token secret, and user ID.
+
+For non-Rails projects, you must require this task in your `Rakefile`:
+
+```ruby
+# Rakefile
+load "paperclip/dropbox/tasks.rake"
+```
+
+## Configuration
 
 Example:
 
@@ -25,20 +76,13 @@ class User < ActiveRecord::Base
 end
 ```
 
-Valid options for `#has_attached_file` are:
-
-- `:dropbox_credentials` – A Hash, a File, or a path to the file where your
-  Dropbox configuration is located
-
-- `:dropbox_options` – A Hash that accepts some Dropbox-specific options (they
-  are explained more below)
-
-## Configuration
-
 ### The `:dropbox_credentials` option
 
-It's best to put your Dropbox credentials into a `dropbox.yml`, and pass the path to
-that file to `:dropbox_credentials`. One example of that YAML file:
+This can be a hash or path to a YAML file containing the keys listed in the
+example below. These are obtained from your Dropbox app settings and the
+authorization Rake task.
+
+Example `config/dropbox.yml`:
 
 ```erb
 app_key: <%= ENV["DROPBOX_APP_KEY"] %>
@@ -46,106 +90,83 @@ app_secret: <%= ENV["DROPBOX_APP_SECRET"] %>
 access_token: <%= ENV["DROPBOX_ACCESS_TOKEN"] %>
 access_token_secret: <%= ENV["DROPBOX_ACCESS_TOKEN_SECRET"] %>
 user_id: <%= ENV["DROPBOX_USER_ID"] %>
+access_type: <%= ENV["DROPBOX_ACCESS_TYPE"] %>
 ```
 
-This is a good practice; Don't put your credentials directly in your YAML file.
-Instead set them in system environment variables, and then embed them here through ERB.
-
-Note that all credentials mentioned here are required.
+It is good practice to not include the credentials directly in the YAML file.
+Instead you can set them in environment variables and embed them with ERB. Note
+`access_type` must be either `"dropbox"` or `"app_folder"` depending on the
+access type of your app; see **Dropbox Setup** above.
 
-If you don't have your app key and secret yet, go to your [Dropbox apps](https://www.dropbox.com/developers/apps),
-and create a new app there, which will then provide you your app key and secret.
-Note that your app has to have the **Full Dropbox** access level (not the "App folder").
-This is because the uploaded files have to be stored in your `Public` folder.
+You can also nest your credentials in environments (like in your `database.yml`):
 
-If you're a relatively new Dropbox user, you'll have to enable your `Public` folder first by visiting
-[this link](https://www.dropbox.com/enable_public_folder).
-
-After you obtain your app key and secret, you can obtain the rest of the credentials
-through the `dropbox:authorize` rake task, which is described in more detail at the bottom of the readme.
-
-You can also namespace your credentials in `development`, `testing` and `production` environments
-(just like you do in your `database.yml`).
+```erb
+development:
+  app_key: "..."
+  ...
+production:
+  app_key: "..."
+  ...
+```
 
 ### The `:dropbox_options` option
 
-You can pass it 3 options:
+This is a hash containing any of the following options:
 
-- `:path` – A block, provides similar results as Paperclip's `:path` option
-- `:environment` – If you namespaced you credentials with environments, here you
-  can set your environment if you're in a non-Rails application
-- `:unique_filename` – Boolean
+- `:path` – Block, works similarly to Paperclip's `:path` option
+- `:unique_filename` – Boolean, whether to generate unique names for files in
+  the absence of a custom `:path`
+- `:environment` – String, the environment name to use for selecting namespaced
+  credentials in a non-Rails app
 
-The `:path` option works in this way; you give it a block, and the return value
-will be the path that the uploaded file will be saved to. The block yields attachment style,
-and is executed in the scope of the class' instance. For example, let's say you have
+The `:path` option should be a block that returns a path that the uploaded file
+should be saved to. The block yields the attachment style and is executed in the
+scope of the model instance. For example:
 
 ```ruby
 class User < ActiveRecord::Base
   has_attached_file :avatar,
     :storage => :dropbox,
-    :dropbox_credentials => "...",
+    :dropbox_credentials => "#{Rails.root}/config/dropbox.yml",
     :styles => { :medium => "300x300" },
     :dropbox_options => {
-      :path => proc { |style| "#{style}/#{id}_#{avatar.original_filename}"}
+      :path => proc { |style| "#{style}/#{id}_#{avatar.original_filename}" }
     }
 end
 ```
 
-Let's say now that a new user is created with the ID of `23`, and a `photo.jpg` as his
-avatar. The following files would be saved to the Dropbox:
+Let's say now that a new user is created with the ID of `23`, and a `photo.jpg`
+as his avatar. The following files would be saved to the Dropbox:
 
 ```
 Public/original/23_photo.jpg
 Public/medium/23_photo_medium.jpg
 ```
 
-The other file is called `photo_medium.jpg` because style names (other than `original`)
-will always be appended to the filenames, for better management.
-
-Files in Dropbox inside a certain folder have to have **unique filenames**, otherwise exception
-`Paperclip::Storage::Dropbox::FileExists` is thrown. To help you with that, you
-can set
+The other file is called `photo_medium.jpg` because style names (other than
+`original`) will always be appended to the filenames, for better management.
 
-```ruby
-# ...
-    :dropbox_options => {
-      :unique_filename => true
-    }
-```
+Filenames within a Dropbox folder must be unique; uploading a file with a
+duplicate name will throw error `Paperclip::Storage::Dropbox::FileExists`. If
+you don't want to bother crafting your own unique filenames with the `:path`
+option, you can instead set the `:unique_filename` option to true and it will
+take care of that.
 
-That will set `:path` to something that will be unique.
+### URL options
 
-You can also pass in the `:download` option to attachment's `#url`:
+When using `dropbox` access type, the `#url` method of attachments returns a
+URL to a "landing page" that provides a preview of the file and a download link.
+To make `#url` return a direct file download link, set the `:download` option as
+a parameter:
 
 ```ruby
 user.avatar.url(:download => true)
 ```
 
-And that will return a download URL for that attachment (so, if a user clicks to
-that link, the file will be downloaded, as opposed to being opened in the browser).
-
-### The `dropbox:authorize` rake task
-
-You just provide it your app key and secret:
-
-```
-$ rake dropbox:authorize APP_KEY=your_app_key APP_SECRET=your_app_secret
-```
-
-It will provide you an authorization URL which you have to visit, and after that
-it will output the rest of your credentials, which you just copy-paste wherever
-you need to.
-
-If you're in a non-Rails application, to get this rake task, you must require it in
-your `Rakefile`:
-
-```ruby
-# Rakefile
-require "rake"
-require "paperclip/dropbox/rake"
-```
+When using `app_folder` access type, `#url` always returns a direct link, and
+setting the `:download` option simply forces the file to be downloaded even if
+the browser would normally just display it.
 
 ## License
 
-[MIT](https://github.com/janko-m/paperclip-dropbox/blob/master/LICENSE)
+[MIT License](https://github.com/janko-m/paperclip-dropbox/blob/master/LICENSE)

data/lib/paperclip/dropbox/railtie.rb

@@ -2,7 +2,7 @@ module Paperclip
   module Dropbox
     class Railtie < Rails::Railtie
       rake_tasks do
-        load "paperclip/dropbox/tasks/authorize.rake"
+        load "paperclip/dropbox/tasks.rake"
       end
     end
   end

data/lib/paperclip/dropbox/rake.rb

@@ -5,15 +5,15 @@ module Paperclip
     module Rake
       extend self
 
-      def authorize(app_key, app_secret)
+      def authorize(app_key, app_secret, access_type)
         session = create_new_session(app_key, app_secret)
 
-        puts "\nVisit this URL: #{session.get_authorize_url}"
+        puts "Visit this URL: #{session.get_authorize_url}"
         print "And after you approved the authorization confirm it here (y/n): "
 
         assert_answer!
         session.get_access_token
-        dropbox_client = DropboxClient.new(session, "dropbox")
+        dropbox_client = DropboxClient.new(session, access_type)
         account_info = dropbox_client.account_info
 
         puts <<-MESSAGE
@@ -23,7 +23,6 @@ Authorization was successful. Here you go:
 access_token: #{session.access_token.key}
 access_token_secret: #{session.access_token.secret}
 user_id: #{account_info["uid"]}
-
         MESSAGE
       end
 

data/lib/paperclip/dropbox/{tasks/authorize.rake → tasks.rake}

@@ -1,12 +1,13 @@
-require "rake"
-require "paperclip/dropbox/rake" unless defined?(Paperclip::Dropbox::Rake)
+require "paperclip/dropbox/rake"
 
 namespace :dropbox do
   desc "Obtains your Dropbox credentials"
   task :authorize do
     if ENV["APP_KEY"].nil? or ENV["APP_SECRET"].nil?
-      raise ArgumentError, "usage: `rake dropbox:authorize APP_KEY=your_app_key APP_SECRET=your_app_secret`"
+      puts "USAGE: `rake dropbox:authorize APP_KEY=your_app_key APP_SECRET=your_app_secret` ACCESS_TYPE=your_access_type"
+      exit
     end
-    Paperclip::Dropbox::Rake.authorize(ENV["APP_KEY"], ENV["APP_SECRET"])
+
+    Paperclip::Dropbox::Rake.authorize(ENV["APP_KEY"], ENV["APP_SECRET"], ENV["ACCESS_TYPE"] || "dropbox")
   end
 end

data/lib/paperclip/storage/dropbox.rb

@@ -1,6 +1,5 @@
 require 'dropbox_sdk'
 require 'active_support/core_ext/hash/keys'
-require 'active_support/core_ext/hash/slice'
 require 'active_support/inflector/methods'
 require 'yaml'
 require 'erb'
@@ -38,30 +37,47 @@ module Paperclip
       end
 
       def exists?(style)
-        !!dropbox_client.media(path(style))
+        metadata = dropbox_metadata(style)
+        !metadata.nil? && !metadata['is_deleted']
       rescue DropboxError
         false
       end
 
       def url(*args)
-        unless blank?
+        if present?
           style = args.first.is_a?(Symbol) ? args.first : default_style
           options = args.last.is_a?(Hash) ? args.last : {}
           query = options[:download] ? "?dl=1" : ""
 
-          File.join("http://dl.dropbox.com/u/#{user_id}", path_for_url(style) + query)
+          if app_folder_mode
+            dropbox_client.media(path(style))['url'] + query
+          else
+            File.join("http://dl.dropbox.com/u/#{user_id}", path_for_url(style) + query)
+          end
         end
       end
 
       def path(style)
-        File.join("Public", path_for_url(style))
+        if app_folder_mode
+          path_for_url(style)
+        else
+          File.join("Public", path_for_url(style))
+        end
       end
 
       def path_for_url(style)
-        result = instance.instance_exec(style, &file_path)
-        result += extension if result !~ /\.\w{3,4}$/
+        path = instance.instance_exec(style, &file_path)
         style_suffix = (style != default_style ? "_#{style}" : "")
-        result.sub(extension, "#{style_suffix}#{extension}")
+
+        if original_extension && path =~ /#{original_extension}$/
+          path.sub(original_extension, "#{style_suffix}#{original_extension}")
+        else
+          path + style_suffix + original_extension.to_s
+        end
+      end
+
+      def dropbox_metadata(style = default_style)
+        dropbox_client.metadata(path(style))
       end
 
       def copy_to_local_file(style, destination_path)
@@ -70,16 +86,29 @@ module Paperclip
         local_file.close
       end
 
+      def dropbox_client
+        @dropbox_client ||= begin
+          assert_required_keys
+          session = DropboxSession.new(@dropbox_credentials[:app_key], @dropbox_credentials[:app_secret])
+          session.set_access_token(@dropbox_credentials[:access_token], @dropbox_credentials[:access_token_secret])
+          DropboxClient.new(session, @dropbox_credentials[:access_type] || 'dropbox')
+        end
+      end
+
       private
 
-      def extension
-        original_filename[/\.\w{3,4}$/]
+      def original_extension
+        original_filename[/\.[^.]+$/]
       end
 
       def user_id
         @dropbox_credentials[:user_id]
       end
 
+      def app_folder_mode
+        @dropbox_credentials[:access_type] == 'app_folder'
+      end
+
       def file_path
         return @dropbox_options[:path] if @dropbox_options[:path]
 
@@ -90,19 +119,13 @@ module Paperclip
         end
       end
 
-      def dropbox_client
-        @dropbox_client ||= begin
-          assert_required_keys
-          session = DropboxSession.new(@dropbox_credentials[:app_key], @dropbox_credentials[:app_secret])
-          session.set_access_token(@dropbox_credentials[:access_token], @dropbox_credentials[:access_token_secret])
-          DropboxClient.new(session, "dropbox")
-        end
-      end
-
       def assert_required_keys
         [:app_key, :app_secret, :access_token, :access_token_secret, :user_id].each do |key|
           @dropbox_credentials.fetch(key)
         end
+        if @dropbox_credentials[:access_type] and not ['dropbox', 'app_folder'].include?(@dropbox_credentials[:access_type])
+          raise KeyError, ":access_type must be 'dropbox' or 'app_folder'"
+        end
       end
 
       def parse_credentials(credentials)

data/paperclip-dropbox.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |gem|
   gem.name          = "paperclip-dropbox"
-  gem.version       = "1.0.1"
+  gem.version       = "1.1.0"
   gem.platform      = Gem::Platform::RUBY
 
   gem.homepage      = "https://github.com/janko-m/paperclip-dropbox"
@@ -21,11 +21,12 @@ Gem::Specification.new do |gem|
   gem.add_dependency "paperclip", "~> 3.1"
   gem.add_dependency "dropbox-sdk", "~> 1.3"
 
-  gem.add_development_dependency "rake", "~> 0.9"
+  gem.add_development_dependency "rake", ">= 0.9"
   gem.add_development_dependency "rspec", "~> 2.11"
   gem.add_development_dependency "vcr", "~> 2.2"
   gem.add_development_dependency "fakeweb", "~> 1.3"
   gem.add_development_dependency "activerecord", "~> 3.2"
   gem.add_development_dependency "rack-test", "~> 0.6"
   gem.add_development_dependency "sqlite3", "~> 1.3"
+  gem.add_development_dependency "rest-client", "~> 1.6"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paperclip-dropbox
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-21 00:00:00.000000000 Z
+date: 2012-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: paperclip
@@ -48,7 +48,7 @@ dependencies:
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0.9'
   type: :development
@@ -56,7 +56,7 @@ dependencies:
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0.9'
 - !ruby/object:Gem::Dependency
@@ -155,6 +155,22 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
 description: Extends Paperclip with Dropbox storage.
 email:
 - janko.marohnic@gmail.com
@@ -164,7 +180,7 @@ extra_rdoc_files: []
 files:
 - lib/paperclip/dropbox/railtie.rb
 - lib/paperclip/dropbox/rake.rb
-- lib/paperclip/dropbox/tasks/authorize.rake
+- lib/paperclip/dropbox/tasks.rake
 - lib/paperclip/dropbox.rb
 - lib/paperclip/storage/dropbox.rb
 - lib/paperclip-dropbox.rb
@@ -190,6 +206,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -208715218772659661
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
@@ -197,4 +216,3 @@ signing_key:
 specification_version: 3
 summary: Extends Paperclip with Dropbox storage.
 test_files: []
-has_rdoc: