Permalink
Browse files

Merge branch 'documentation' of https://github.com/monde/paperclip

  • Loading branch information...
2 parents d591a64 + 81562b0 commit aee47d8d1b8452168b3bb43197e29c4e22e43cfb @mike-burns mike-burns committed Aug 26, 2011
Showing with 84 additions and 2 deletions.
  1. +76 −2 README.md
  2. +8 −0 test/upfile_test.rb
View
@@ -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)`:
@@ -231,6 +231,80 @@ Paperclip has an interpolation called `:hash` for obfuscating filenames of publi
[https://github.com/thoughtbot/paperclip/pull/416](https://github.com/thoughtbot/paperclip/pull/416)
+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.
+
+ class AddAvatarFingerprintColumnToUser < ActiveRecord::Migration
+ def self.up
+ add_column :users, :avatar_fingerprint, :string
+ end
+
+ def self.down
+ remove_column :users, :avatar_fingerprint
+ 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
-------
@@ -245,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
View
@@ -24,6 +24,14 @@ class << file
assert_equal content_type, file.content_type
end
+
+ should "return a content_type of text/plain on a real file whose content_type is determined with the file command" do
+ file = File.new(File.join(File.dirname(__FILE__), "..", "LICENSE"))
+ class << file
+ include Paperclip::Upfile
+ end
+ assert_equal 'text/plain', file.content_type
+ end
end
end

0 comments on commit aee47d8

Please sign in to comment.