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

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)`:
@@ -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

test/upfile_test.rb

@@ -24,6 +24,14 @@ class UpfileTest < Test::Unit::TestCase
 
         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