Documentation for custom processors, dynamic styles, and dynamic proc…

…essors.

An implemenation of the watermark processor alluded to is in this gist
https://gist.github.com/1171081

README.md

@@ -25,7 +25,7 @@ that it does, on your command line, run `which convert` (one of the ImageMagick
 utilities). This will give you the path where that utility is installed. For
 example, it might return `/usr/local/bin/convert`.
 
-Then, in your environment config file, let Paperclip know to look there by adding that 
+Then, in your environment config file, let Paperclip know to look there by adding that
 directory to its path.
 
 In development mode, you might add this line to `config/environments/development.rb)`:
@@ -233,7 +233,10 @@ Paperclip has an interpolation called `:hash` for obfuscating filenames of publi
 
 MD5 Checksum / Fingerprint
 -------
-A MD5 checksum of the original file assigned will be placed in the model if it has an attribute named fingerprint.  Following the user model migration example above, the migration would look like the following.
+
+A MD5 checksum of the original file assigned will be placed in the model if it
+has an attribute named fingerprint.  Following the user model migration example
+above, the migration would look like the following.
 
     class AddAvatarFingerprintColumnToUser < ActiveRecord::Migration
       def self.up
@@ -245,6 +248,63 @@ A MD5 checksum of the original file assigned will be placed in the model if it h
       end
     end
 
+Custom Attachment Processors
+-------
+
+Custom attachment processors can be implemented and their only requirement is
+to inherit from `Paperclip::Processor` (see `lib/paperclip/processor.rb`).
+For example, when `:styles` are specified for an image attachment, the
+thumbnail processor (see `lib/paperclip/thumbnail.rb`) is loaded without having
+to specify it as a `:processor` parameter to `has_attached_file`.  When any
+other processor is defined it must be called out in the `:processors`
+parameter if it is to be applied to the attachment.  The thumbnail processor
+uses the imagemagick `convert` command to do the work of resizing image
+thumbnails.  It would be easy to create a custom processor that watermarks
+an image using imagemagick's `composite` command.  Following the
+implementation pattern of the thumbnail processor would be a way to implement a
+watermark processor.  All kinds of attachment processors can be created;
+a few utility examples would be compression and encryption processors.
+
+
+Dynamic Configuration
+---------------------
+
+Callable objects (labdas, Procs) can be used in a number of places for dynamic
+configuration throughout Paperclip.  This strategy exists in a number of
+components of the library but is most significant in the possibilities for
+allowing custom styles and processors to be applied for specific model
+instances, rather than applying defined styles and processors across all
+instances.
+
+Dynamic Styles:
+
+Imagine a user model that had different styles based on the role of the user.
+Perhaps some users are bosses (e.g. a User model instance responds to #boss?)
+and merit a bigger avatar thumbnail than regular users. The configuration to
+determine what style parameters are to be used based on the user role might
+look as follows where a boss will receive a `300x300` thumbnail otherwise a
+`100x100` thumbnail will be created.
+
+    class User < ActiveRecord::Base
+      has_attached_file :avatar, :styles => lambda { |attachment| { :thumb => (attachment.instance.boss? ? "300x300>" : "100x100>") }
+    end
+
+Dynamic Processors:
+
+Another contrived example is a user model that is aware of which file processors
+should be applied to it (beyond the implied `thumbnail` processor invoked when
+`:styles` are defined). Perhaps we have a watermark processor available and it is
+only used on the avatars of certain models.  The configuration for this might be
+where the instance is queried for which processors should be applied to it.
+Presumably some users might return `[:thumbnail, :watermark]` for its
+processors, where a defined `watermark` processor is invoked after the
+`thumbnail` processor already defined by Paperclip.
+
+    class User < ActiveRecord::Base
+      has_attached_file :avatar, :processors => lambda { |instance| instance.processors }
+      attr_accessor :watermark
+    end
+
 Testing
 -------
 
@@ -259,7 +319,7 @@ If you'd like to contribute a feature or bugfix: Thanks! To make sure your
 fix/feature has a high chance of being included, please read the following
 guidelines:
 
-1. Ask on the mailing list[http://groups.google.com/group/paperclip-plugin], or 
+1. Ask on the mailing list[http://groups.google.com/group/paperclip-plugin], or
    post a new GitHub Issue[http://github.com/thoughtbot/paperclip/issues].
 2. Make sure there are tests! We will not accept any patch that is not tested.
    It's a rare time when explicit tests aren't needed. If you have questions