Commit 81562b0f by Mike Mondragon

Documentation for custom processors, dynamic styles, and dynamic processors.

An implemenation of the watermark processor alluded to is in this gist
https://gist.github.com/1171081
parent f815b8b3
......@@ -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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment