Dynamic Paperclip

Dynamic Paperclip is an extension to the wonderful Paperclip gem and a Ruby on Rails engine that allows for the creation of Paperclip attachment styles on-the-fly.

Instead of defining your attachment styles in your model, Dynamic Paperclip allows you to generate URL's for arbitrary attachment styles (usually in your view), effectively pushing style definition there. When the browser requests that asset, if it has not already been processed, it is then processed on-the-fly and sent back to the browser. If the style has already been processed, it's served just like any other static asset.

Getting started

Requirements

Dynamic Paperclip requires Paperclip 3.5.0 or above and Rails 3.2.0 or above (although it may work on earlier versions, it's just untested at the moment).

It also only currently supports Paperclip's File Storage.

Application

Add the gem to your gemfile:

gem 'dynamic_paperclip'

Run the bundle command to install it.

After you install the gem, you need to run the generator:

rails generate dynamic_paperclip:install

This will install an initializer that sets up a secret key used in validating that dynamic asset URL's originated from your application.

Now, you're ready to start using Dynamic Paperclip. Change any attachment definitions that you'd like to make dynamic from:

has_attached_file :avatar

To:

has_dynamic_attached_file :avatar

You can continue defining styles there, too, you don't need to move over entirely to dynamic styles. You can have both!

Note: Dynamic Paperclip requires that the :style and either the :id or :id_partition be included in the :url that you specify when defining the attachment. Paperclip includes them by default, so this only applies if you've specified your own.

Then, whenever you'd like a URL to a dynamic style, simply call #dynamic_url instead of #url on the attachment, passing it the style definition that you would normally define in the :styles hash on has_attached_file:

@user.avatar.dynamic_url('100x100#')

Server Configuration

If you're using Rails to serve static assets, then no configuration is required. But if you're not, which you shouldn't be in any production environment, then you just need to make sure that your HTTP server is configured to serve static assets if they exist, but pass the request along to your Rails application if they do not.

For example, on Nginx, this would be accomplished with something along the lines of:

upstream rails {
  # ...
}

server {
  # ...

  try_files $uri @rails

  location @rails {
    # ...

    proxy_pass  http://rails;
  }
}

This basically says "If the requested URI exists, send that to the browser, if not, pass it along to the Rails app.", and is a pretty standard Nginx setup.

Why?

Because as your Rails application grows, you may discover that you have a large number of attachment styles. This is slowing down your requests, because every time a user attempts to upload a file, Paperclip must process each and every one of those styles right then and there, in the middle of the request.

Also, when dealing with images, I think it makes more sense to specify the dimensions of a thumbnail in the view that needs it, and not in the model.

How does this wizardry work?

It's pretty simple, actually. When you define a dynamic attachment on your model, Dynamic Paperclip defines a route in your application that routes the URL you've specified (or Paperclip's default) to the DynamicPaperclip::AttachmentStylesController.

For security purposes, the class is interpolated and thus hardcoded into the route. So, if your Paperclip attachment definition looks like:

class User
  has_dynamic_attached_file :avatar, url: '/system/:class/:attachment/:id/:style'
end

Dynamic Paperclip will generate the following route:

get '/system/users/:attachment/:id/dynamic_:definition', to: 'DynamicPaperclip::AttachmentStyles#generate_user'

Now, in your view, you might call something like this:

@user.avatar.dynamic_url('50x50')

Which will return the following url (assuming a JPG avatar and a User ID of 42):

/system/users/avatars/42/dynamic_50x50.jpg?s=secrethash

When your visitor's browser requests that URL, if that particular style has already been processed, it'll be served up by your HTTP server, but if it hasn't, Rails will route it to our controller, which validates that "secrethash" to ensure that the dynamic URL was generated by your application, and not some third-party, then simply tells Paperclip to process that style by extracting the definition from the stye name, and then sends it back to your visitor via #send_file.

On subsequent requests, the attachment will already exist, and your HTTP server will simply return it without ever hitting your Rails application. Sweet!

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request