Merge pull request #122 from ScotterC/updates

Moved Readme to Markdown

Author: Scott Carleton

.rbenv-version

@@ -2,14 +2,13 @@ language: ruby
 
 rvm:
   - 2.1
-  - 1.9.3
+  - 2.0
   - rbx-19mode
 
 gemfile:
-  - gemfiles/rails3_1.gemfile
-  - gemfiles/rails3_2.gemfile
-  - gemfiles/rails4.gemfile
-  - gemfiles/rails4_2.gemfile
+  - gemfiles/3.2.gemfile
+  - gemfiles/4.0.gemfile
+  - gemfiles/4.1.gemfile
 
 sudo: false
 

.travis.yml

@@ -1,15 +1,19 @@
-appraise "rails3_1" do
-  gem "rails", "~> 3.1.12"
+appraise "3.2" do
+  gem "rails", "~> 3.2.15"
+  gem "delayed_paperclip", path: "../"
 end
 
-appraise "rails3_2" do
-  gem "rails", "~> 3.2.17"
+appraise "4.0" do
+  gem "rails", "~> 4.0.0"
+  gem "delayed_paperclip", path: "../"
 end
 
-appraise "rails4" do
-  gem "rails", "~> 4.0.3"
+appraise "4.1" do
+  gem "rails", "~> 4.1.0"
+  gem "delayed_paperclip", path: "../"
 end
 
-appraise "rails4_2" do
-  gem "rails", "~> 4.2.0.beta2"
+appraise "4.2" do
+  gem "rails", "~> 4.2.0"
+  gem "delayed_paperclip", path: "../"
 end

Appraisals

@@ -0,0 +1,277 @@
+Delayed::Paperclip [![Build Status](https://travis-ci.org/jrgifford/delayed_paperclip.svg?branch=master)](https://travis-ci.org/jrgifford/delayed_paperclip) [![Code Climate](https://codeclimate.com/github/jrgifford/delayed_paperclip.png)](https://codeclimate.com/github/jrgifford/delayed_paperclip)
+======================================================================================
+
+
+DelayedPaperclip lets you process your [Paperclip](http://github.com/thoughtbot/paperclip) attachments in a
+background task with [DelayedJob](https://github.com/collectiveidea/delayed_job), [Resque](https://github.com/resque/resque) or [Sidekiq](https://github.com/mperham/sidekiq).
+
+Why?
+----
+
+The most common use case for Paperclip is to easily attach image files
+to ActiveRecord models. Most of the time these image files will have
+multiple styles and will need to be resized when they are created. This
+is usually a pretty [slow operation](http://www.jstorimer.com/ruby/2010/01/05/speep-up-your-paperclip-tests.html) and should be handled in a
+background task.
+
+I’m sure that everyone knows this, this gem just makes it easy to do.
+
+Installation
+------------
+
+Install the gem:
+
+````
+gem install delayed_paperclip
+````
+
+Or even better, add it to your Gemfile.
+
+````
+source "https://rubygems.org"
+gem 'delayed_paperclip'
+````
+
+Dependencies:
+
+-   Paperclip
+-   DJ, Resque or Sidekiq
+
+Usage
+-----
+
+In your model:
+
+````ruby
+class User < ActiveRecord::Base
+  has_attached_file :avatar, styles: {
+                                       medium: "300x300>",
+                                       thumb: "100x100>"
+                                     }
+
+  process_in_background :avatar
+end
+````
+
+Use your Paperclip attachment just like always in controllers and views.
+
+To select between using Resque or Delayed::Job, just install and
+configure your choice properly within your application, and
+delayed_paperclip will do the rest. It will detect which library is
+loaded and make a decision about which sort of job to enqueue at that
+time.
+
+### Resque
+
+Make sure that you have [Resque](https://github.com/resque/resque) up and running. The jobs will be
+dispatched to the <code>:paperclip</code> queue, so you can correctly
+dispatch your worker. Configure resque and your workers exactly as you
+would otherwise.
+
+### DJ
+
+Just make sure that you have DJ up and running.
+
+### Sidekiq
+
+Make sure that [Sidekiq](http://github.com/mperham/sidekiq) is running and listening to the
+`paperclip` queue, either by adding it to your
+`sidekiq.yml` config file under `- queues:` or by
+passing the command line argument `-q paperclip` to Sidekiq.
+
+### Displaying images during processing
+
+In the default setup, when you upload an image for the first time and
+try to display it before the job has been completed, Paperclip will be
+none the wiser and output the url of the image which is yet to be
+processed, which will result in a broken image link being displayed on
+the page.
+
+To have the missing image url be outputted by paperclip while the image is being processed, all you need to do is add a
+`#{attachment_name}_processing` column to the specific model you want
+to enable this feature for. This feature gracefully degrades and will not affect models which do not have the column added to them.
+
+````ruby
+class AddAvatarProcessingToUser < ActiveRecord::Migration
+  def self.up
+    add_column :users, :avatar_processing, :boolean
+  end
+
+  def self.down
+    remove_column :users, :avatar_processing
+  end
+end
+
+@user = User.new(avatar: File.new(...))
+@user.save
+@user.avatar.url #=> "/images/original/missing.png"
+Delayed::Worker.new.work_off
+
+@user.reload
+@user.avatar.url #=> "/system/images/3/original/IMG_2772.JPG?1267562148"
+````
+
+#### Custom image for processing
+
+This is useful if you have a difference between missing images and
+images currently being processed.
+
+````ruby
+class User < ActiveRecord::Base
+  has_attached_file :avatar
+
+  process_in_background :avatar, processing_image_url: "/images/original/processing.jpg"
+end
+
+@user = User.new(avatar: File.new(...))
+@user.save
+@user.avatar.url #=> "/images/original/processing.png"
+Delayed::Worker.new.work_off
+
+@user.reload
+@user.avatar.url #=> "/system/images/3/original/IMG_2772.JPG?1267562148"
+````
+
+You can also define a custom logic for `processing_image_url`, for
+example to display the original\
+picture while specific formats are being processed.
+
+````ruby
+class Item < ActiveRecord::Base
+  has_attached_file :photo
+
+  process_in_background :photo, processing_image_url: :processing_image_fallback
+
+  def processing_image_fallback
+    options = photo.options
+    options[:interpolator].interpolate(options[:url], photo, :original)
+  end
+end
+````
+
+#### Have processing? status available, but construct image URLs as if delayed_paperclip wasn’t present
+
+If you define the `#{attachment_name}_processing` column, but set the
+`url_with_processing` option to false, this opens up other options (other than modifying the url that paperclip returns) for giving feedback to the user while the image is processing. This is useful for advanced situations, for example when dealing with caching systems.
+
+Note especially the method #processing? which passes through the value
+of the boolean created via migration.
+
+````ruby
+class User < ActiveRecord::Base
+  has_attached_file :avatar
+
+  process_in_background :avatar, url_with_processing: false
+end
+
+@user = User.new(avatar: File.new(...))
+@user.save
+@user.avatar.url #=> "/system/images/3/original/IMG_2772.JPG?1267562148"
+@user.avatar.processing? #=> true
+Delayed::Worker.new.work_off
+
+@user.reload
+@user.avatar.url #=> "/system/images/3/original/IMG_2772.JPG?1267562148"
+@user.avatar.processing? #=> false
+````
+
+#### Only process certain styles
+
+This is useful if you don’t want the background job to reprocess all
+styles.
+
+````ruby
+class User < ActiveRecord::Base
+  has_attached_file :avatar, styles: { small: "25x25#", medium: "50x50x" }
+
+  process_in_background :avatar, only_process: [:small]
+end
+````
+
+Like paperclip, you could also supply a lambda function to define
+`only_process` dynamically.
+
+````ruby
+class User < ActiveRecord::Base
+  has_attached_file :avatar, styles: { small: "25x25#", medium: "50x50x" }
+
+  process_in_background :avatar, only_process: lambda { |a| a.instance.small_supported? ? [:small, :large] : [:large] }
+end
+````
+
+#### Split processing
+
+You can process some styles in the foreground and some in the background
+by setting `only_process` on both `has_attached_file` and
+`process_in_background`.
+
+````ruby
+class User < ActiveRecord::Base
+  has_attached_file :avatar, styles: { small: "25x25#", medium: "50x50x" }, only_process: [:small]
+
+  process_in_background :avatar, only_process: [:medium]
+end
+````
+
+#### Reprocess Without Delay
+
+This is useful if you don’t want the background job. It accepts
+individual styles to. Take note, normal `reprocess!` does not accept styles as arguments anymore. It will delegate to DelayedPaperclip and
+reprocess all styles.
+
+````ruby
+class User < ActiveRecord::Base
+  has_attached_file :avatar, styles: { small: "25x25#", medium: "50x50x" }
+
+  process_in_background :avatar
+end
+
+@user.avatar.url #=> "/system/images/3/original/IMG_2772.JPG?1267562148"
+@user.avatar.reprocess_without_delay!(:medium)
+````
+
+Defaults
+--------
+
+Global defaults for all delayed_paperclip instances in your app can be
+defined by changing the DelayedPaperclip.options Hash, this can be useful for setting a default ‘processing image,’ so you won’t have to define it in every `process_in_background` definition.
+
+If you’re using Rails you can define a Hash with default options in
+config/application.rb or in any of the config/environments/\*.rb files on `config.delayed_paperclip_defaults`, these will get merged into DelayedPaperclip.options as your Rails app boots. An example:
+
+````
+module YourApp
+  class Application < Rails::Application
+    # Other code...
+
+    config.delayed_paperclip_defaults = {
+        url_with_processing: true,
+        processing_image_url: 'custom_processing.png'
+    }
+  end
+end
+````
+
+What if I’m not using images?
+-----------------------------
+
+This library works no matter what kind of post-processing you are doing
+with Paperclip.
+
+Does it work with s3?
+---------------------
+
+Yes.
+
+Contributing
+------------
+
+Checkout out CONTRIBUTING. In short, you’ll need a redis server running
+for testing. Run all tests with
+
+````
+# Rspec on all versions
+rake appraisal spec
+# Test Unit on all versions (deprecated)
+rake appraisal test
+````