Extensive documentation, adding ability to crop thumbnails.

git-svn-id: https://svn.thoughtbot.com/plugins/paperclip/trunk@171 7bbfaf0e-4d1d-0410-9690-a8bb5f8ef2aa

README

-Paperclip
-=========
+=Paperclip
 
 
-Paperclip is a lightweight attachment manager for ActiveRecord. It saves and manages your attachments, be they images or Word Docs, with one line of code. You can automatically thumbnail images as they're uploaded, and you don't have to worry about installing any ruby-specific libraries. You don't have to worry about compiling headaches with RMagick, concurrency issues and race conditions with MiniMagick, or unsupported image types with ImageScience. All you need is a working Image- or GraphicsMagick installation -- the convert command is all you need.
+Paperclip is a lightweight attachment manager for ActiveRecord. It saves and manages your attachments, be they images or Word Docs, with one line of code. You can automatically thumbnail images as they're uploaded, and you don't have to worry about installing any ruby-specific libraries. You don't have to worry about compiling headaches with RMagick, concurrency issues and race conditions with MiniMagick, or unsupported image types with ImageScience. All you need is a working Image- or GraphicsMagick installation -- the +convert+ command is all you need.
 
 
-Paperclip uses the filesystem to save your files. You specify a root that the files will be saved to, and, if you're attaching images, any other formats they need to be converted to, and they'll all be saved to the right place when your object saves. They can even validate beforehand, so you'll know if your user tries to upload an HTML doc as an image.
+Paperclip uses the filesystem to save your files. You specify a root that the files will be saved to, and, if you're attaching images, any other sizes they need to be converted to, and they'll all be saved to the right place when your object saves.
 
 
-Usage
------
+See the documentation for the +has_attached_file+ method for extensive details.
+
+==Usage
 
 
 In your model:
 In your model:
 
 
-class Photo < ActiveRecord::Base
+  class Photo < ActiveRecord::Base
     has_attached_file :image, :thumbnails => { :medium => "300x300>", :thumb => "100x100>" }
     has_attached_file :image, :thumbnails => { :medium => "300x300>", :thumb => "100x100>" }
-end
+  end
 
 
 In your edit and new views:
 In your edit and new views:
 
 
-<% form_for :photo, @photo, :url => photo_path do |form| %>
+  <% form_for :photo, @photo, :url => photo_path, :html => { :multipart => true } do |form| %>
     <%= form.file_field :image %>
     <%= form.file_field :image %>
-<% end %>
+  <% end %>
 
 
 In your controller:
 In your controller:
 
 
-def create
+  def create
     @photo = Photo.create( params[:photo] )
     @photo = Photo.create( params[:photo] )
-end
+  end
 
 
 In your show view:
 In your show view:
 
 
-<%= image_tag @photo.image_url %>
-<%= image_tag @photo.image_url(:original) %>
-<%= image_tag @photo.image_url(:medium) %>
-<%= image_tag @photo.image_url(:thumb) %>
-
+  <%= image_tag @photo.image_url %>
+  <%= image_tag @photo.image_url(:original) %>
+  <%= image_tag @photo.image_url(:medium) %>
+  <%= image_tag @photo.image_url(:thumb) %>

Rakefile

@@ -7,16 +7,25 @@ task :default => :test
 
 
 desc 'Test the paperclip plugin.'
 desc 'Test the paperclip plugin.'
 Rake::TestTask.new(:test) do |t|
 Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib'
+  t.libs << 'lib' << 'profile'
   t.pattern = 'test/**/*_test.rb'
   t.pattern = 'test/**/*_test.rb'
   t.verbose = true
   t.verbose = true
 end
 end
 
 
 desc 'Generate documentation for the paperclip plugin.'
 desc 'Generate documentation for the paperclip plugin.'
 Rake::RDocTask.new(:rdoc) do |rdoc|
 Rake::RDocTask.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
+  rdoc.rdoc_dir = 'doc'
   rdoc.title    = 'Paperclip'
   rdoc.title    = 'Paperclip'
   rdoc.options << '--line-numbers' << '--inline-source'
   rdoc.options << '--line-numbers' << '--inline-source'
   rdoc.rdoc_files.include('README')
   rdoc.rdoc_files.include('README')
   rdoc.rdoc_files.include('lib/**/*.rb')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
 end
+
+desc 'Clean up files.'
+task :clean do |t|
+  FileUtils.rm_rf "doc"
+  FileUtils.rm_rf "repository"
+  FileUtils.rm_rf "tmp"
+  FileUtils.rm "test/debug.log" rescue nil
+  FileUtils.rm "test/paperclip.db" rescue nil
+end
\ No newline at end of file

init.rb

 require File.join(File.dirname(__FILE__), "lib", "paperclip")
 require File.join(File.dirname(__FILE__), "lib", "paperclip")
 ActiveRecord::Base.extend( Thoughtbot::Paperclip::ClassMethods )
 ActiveRecord::Base.extend( Thoughtbot::Paperclip::ClassMethods )
+File.send :include, Thoughtbot::Paperclip::Upfile
\ No newline at end of file

test/models.rb

@@ -7,16 +7,35 @@ begin
     table.column :document_file_name, :string
     table.column :document_file_name, :string
     table.column :document_content_type, :string
     table.column :document_content_type, :string
   end
   end
+  ActiveRecord::Base.connection.create_table :non_standards do |table|
+    table.column :resume_file_name, :string
+    table.column :resume_content_type, :string
+    table.column :avatar_file_name, :string
+    table.column :avatar_content_type, :string
+  end
 rescue Exception
 rescue Exception
 end
 end
 
 
 class Foo < ActiveRecord::Base
 class Foo < ActiveRecord::Base
   has_attached_file :image, :attachment_type => :image,
   has_attached_file :image, :attachment_type => :image,
                     :thumbnails => { :thumb  => "100x100>", :medium => "300x300>" },
                     :thumbnails => { :thumb  => "100x100>", :medium => "300x300>" },
-                    :path_prefix => "."
+                    :path_prefix => "./repository"
 end
 end
 
 
 class Bar < ActiveRecord::Base
 class Bar < ActiveRecord::Base
   has_attached_file :document, :attachment_type => :document,
   has_attached_file :document, :attachment_type => :document,
-                    :path_prefix => "."
+                    :path_prefix => "./repository"
+end
+
+class NonStandard < ActiveRecord::Base
+  has_attached_file :resume, :attachment_type => :document,
+                    :path_prefix => "/tmp",
+                    :path => ":attachment_:id_:name"
+  has_attached_file :avatar, :attachment_type => :image,
+                    :thumbnails => { :cropped => "200x10#",
+                                     :bigger  => "1000x1000",
+                                     :smaller => "200x200>",
+                                     :square  => "150x150#" },
+                    :path_prefix => "./repository",
+                    :path => ":class/:attachment/:id/:style_:name"
 end
 end
\ No newline at end of file

test/paperclip_images_test.rb

@@ -17,15 +17,15 @@ class PaperclipImagesTest < Test::Unit::TestCase
 
 
   def test_should_save_the_file_and_its_thumbnails
   def test_should_save_the_file_and_its_thumbnails
     assert @foo.save
     assert @foo.save
-    assert File.exists?( @foo.image_filename(:original) ), @foo.image_filename(:original)
-    assert File.exists?( @foo.image_filename(:medium) ), @foo.image_filename(:medium)
-    assert File.exists?( @foo.image_filename(:thumb) ), @foo.image_filename(:thumb)
-    assert File.size?(   @foo.image_filename(:original) )
-    assert File.size?(   @foo.image_filename(:medium) )
-    assert File.size?(   @foo.image_filename(:thumb) )
-    out = `identify '#{@foo.image_filename(:original)}'`; assert out.match("405x375"); assert $?.exitstatus == 0
-    out = `identify '#{@foo.image_filename(:medium)}'`;   assert out.match("300x278"); assert $?.exitstatus == 0
-    out = `identify '#{@foo.image_filename(:thumb)}'`;    assert out.match("100x93");  assert $?.exitstatus == 0
+    assert File.exists?( @foo.image_file_name(:original) ), @foo.image_file_name(:original)
+    assert File.exists?( @foo.image_file_name(:medium) ), @foo.image_file_name(:medium)
+    assert File.exists?( @foo.image_file_name(:thumb) ), @foo.image_file_name(:thumb)
+    assert File.size?(   @foo.image_file_name(:original) )
+    assert File.size?(   @foo.image_file_name(:medium) )
+    assert File.size?(   @foo.image_file_name(:thumb) )
+    out = `identify '#{@foo.image_file_name(:original)}'`; assert out.match("405x375"); assert $?.exitstatus == 0
+    out = `identify '#{@foo.image_file_name(:medium)}'`;   assert out.match("300x278"); assert $?.exitstatus == 0
+    out = `identify '#{@foo.image_file_name(:thumb)}'`;    assert out.match("100x93");  assert $?.exitstatus == 0
   end
   end
 
 
   def test_should_validate_to_make_sure_the_thumbnails_exist
   def test_should_validate_to_make_sure_the_thumbnails_exist
@@ -36,7 +36,7 @@ class PaperclipImagesTest < Test::Unit::TestCase
   
   
   def test_should_delete_all_thumbnails_on_destroy
   def test_should_delete_all_thumbnails_on_destroy
     assert @foo.save
     assert @foo.save
-    names = [:original, :medium, :thumb].map{|style| @foo.image_filename(style) }
+    names = [:original, :medium, :thumb].map{|style| @foo.image_file_name(style) }
     assert @foo.destroy
     assert @foo.destroy
     names.each {|path| assert !File.exists?( path ), path }
     names.each {|path| assert !File.exists?( path ), path }
   end
   end

test/paperclip_non_standard_test.rb

+require 'test/unit'
+require File.dirname(__FILE__) + "/test_helper.rb"
+require File.dirname(__FILE__) + "/../init.rb"
+require File.join(File.dirname(__FILE__), "models.rb")
+
+class PaperclipNonStandardTest < Test::Unit::TestCase
+  def setup
+    assert @ns = NonStandard.new
+    assert @resume = File.new(File.join(File.dirname(__FILE__), 'fixtures', 'test_document.doc'))
+    assert @avatar = File.new(File.join(File.dirname(__FILE__), 'fixtures', 'test_image.jpg'))
+    assert @ns.resume = @resume
+    assert @ns.avatar = @avatar
+  end
+
+  def test_should_validate_before_save
+    assert @ns.avatar_valid?
+    assert @ns.valid?
+  end
+
+  def test_should_save_the_created_file_to_the_final_asset_directory
+    assert @ns.save
+    assert File.exists?( @ns.resume_file_name )
+    assert File.exists?( @ns.avatar_file_name(:original) )
+    assert File.exists?( @ns.avatar_file_name(:bigger) )
+    assert File.exists?( @ns.avatar_file_name(:cropped) )
+    assert File.size?(   @ns.avatar_file_name(:original) )
+    assert File.size?(   @ns.avatar_file_name(:bigger) )
+    assert File.size?(   @ns.avatar_file_name(:cropped) )
+    out = `identify '#{@ns.avatar_file_name(:original)}'`; assert_match /405x375/, out, out;  assert $?.exitstatus == 0
+    out = `identify '#{@ns.avatar_file_name(:bigger)}'`;   assert_match /1000x926/, out, out; assert $?.exitstatus == 0
+    out = `identify '#{@ns.avatar_file_name(:cropped)}'`;  assert_match /200x10/, out, out;   assert $?.exitstatus == 0
+  end
+
+  def test_should_validate
+    assert @ns.save
+    assert @ns.resume_valid?
+    assert @ns.avatar_valid?
+    assert @ns.valid?
+  end
+
+  def test_should_default_to_original_for_path_and_url
+    assert_equal @ns.resume_file_name(:original), @ns.resume_file_name
+    assert_equal @ns.resume_url(:original), @ns.resume_url
+
+    assert_equal @ns.avatar_file_name(:original), @ns.avatar_file_name
+    assert_equal @ns.avatar_url(:original), @ns.avatar_url
+  end
+
+  def test_should_delete_files_on_destroy
+    assert @ns.save
+    assert File.exists?( @ns.resume_file_name ), @ns.resume_file_name
+    assert File.exists?( @ns.avatar_file_name(:original) )
+    assert File.exists?( @ns.avatar_file_name(:bigger) )
+    assert File.exists?( @ns.avatar_file_name(:cropped) )
+
+    resume_file_name  = @ns.resume_file_name
+    avatar_file_names = [:original, :bigger, :cropped].map{|style| @ns.avatar_file_name(style) }
+    assert @ns.destroy
+    assert !File.exists?( resume_file_name ), resume_file_name
+    avatar_file_names.each do |name|
+      assert !File.exists?(name), name
+    end
+  end
+
+end
\ No newline at end of file

test/paperclip_test.rb

@@ -17,7 +17,7 @@ class PaperclipTest < Test::Unit::TestCase
 
 
   def test_should_save_the_created_file_to_the_final_asset_directory
   def test_should_save_the_created_file_to_the_final_asset_directory
     assert @bar.save
     assert @bar.save
-    assert File.exists?( @bar.document_filename )
+    assert File.exists?( @bar.document_file_name )
   end
   end
 
 
   def test_should_validate
   def test_should_validate
@@ -27,17 +27,17 @@ class PaperclipTest < Test::Unit::TestCase
   end
   end
   
   
   def test_should_default_to_original_for_path_and_url
   def test_should_default_to_original_for_path_and_url
-    assert_equal @bar.document_filename(:original), @bar.document_filename
+    assert_equal @bar.document_file_name(:original), @bar.document_file_name
     assert_equal @bar.document_url(:original), @bar.document_url
     assert_equal @bar.document_url(:original), @bar.document_url
   end
   end
   
   
   def test_should_delete_files_on_destroy
   def test_should_delete_files_on_destroy
     assert @bar.save
     assert @bar.save
-    assert File.exists?( @bar.document_filename ), @bar.document_filename
+    assert File.exists?( @bar.document_file_name ), @bar.document_file_name
     
     
-    document_filename = @bar.document_filename
+    document_file_name = @bar.document_file_name
     assert @bar.destroy
     assert @bar.destroy
-    assert !File.exists?( document_filename ), document_filename
+    assert !File.exists?( document_file_name ), document_file_name
   end
   end
 
 
 end
 end
\ No newline at end of file