Delayed_paperclip lets you process your Paperclip attachments in a background task with delayed_job, Resque or Sidekiq.
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 and should be handled in a background task.
I’m sure that everyone knows this, this gem just makes it easy to do.
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
In your model:
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.
Make sure that you have Resque up and running. The jobs will be dispatched to the :paperclip
queue, so you can correctly dispatch your worker. Configure resque and your workers exactly as you would otherwise.
Just make sure that you have DJ up and running.
Make sure that 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.
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.
class AddAvatarProessingToUser < 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"
This is useful if you have a difference between missing images and images currently
being processed.
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"
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.
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
This is useful if you don’t want the background job to reprocess all styles.
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.
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
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.
class User < ActiveRecord::Base
has_attached_file :avatar, :styles => { :small => "25x25#", :medium => "50x50x" }, :only_process => [:small]
process_in_background :avatar, :only_process => [:medium]
end
You can define an error handler to be called if `:whiny => true` is set on the attachment and errors occur during processing. Any object that response to `#call` can be used.
class User < ActiveRecord::Base
has_attached_file :avatar, :styles => { :small => "25x25#", :medium => "50x50x" }
process_in_background :avatar, :on_error => lambda {|a, errors| raise "Something bad happened" }
end
`errors` is an array of error strings. Unfortunately, they tend to just be the names of exceptions. This is a limitation of Paperclip.
The error handler is called before the processing flag is set back to false.
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.
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)
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
This library works no matter what kind of post-processing you are doing with Paperclip.
Yes.
Checkout out CONTRIBUTING. In short, you’ll need a redis server running for testing. Run all tests with
rake