paperclip-v2_7-patched-ruby-1_8_6 2.7.5
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/.gitignore +23 -0
- data/.travis.yml +14 -0
- data/Appraisals +20 -0
- data/CONTRIBUTING.md +38 -0
- data/Gemfile +5 -0
- data/LICENSE +26 -0
- data/NEWS +69 -0
- data/README.md +444 -0
- data/Rakefile +41 -0
- data/cucumber/paperclip_steps.rb +6 -0
- data/features/basic_integration.feature +48 -0
- data/features/rake_tasks.feature +68 -0
- data/features/step_definitions/attachment_steps.rb +65 -0
- data/features/step_definitions/html_steps.rb +15 -0
- data/features/step_definitions/rails_steps.rb +193 -0
- data/features/step_definitions/s3_steps.rb +14 -0
- data/features/step_definitions/web_steps.rb +209 -0
- data/features/support/env.rb +8 -0
- data/features/support/fakeweb.rb +3 -0
- data/features/support/fixtures/.boot_config.rb.swo +0 -0
- data/features/support/fixtures/boot_config.txt +15 -0
- data/features/support/fixtures/gemfile.txt +5 -0
- data/features/support/fixtures/preinitializer.txt +20 -0
- data/features/support/paths.rb +28 -0
- data/features/support/rails.rb +46 -0
- data/features/support/selectors.rb +19 -0
- data/gemfiles/rails2.gemfile +9 -0
- data/gemfiles/rails3.gemfile +9 -0
- data/gemfiles/rails3_1.gemfile +9 -0
- data/gemfiles/rails3_2.gemfile +9 -0
- data/generators/paperclip/USAGE +5 -0
- data/generators/paperclip/paperclip_generator.rb +27 -0
- data/generators/paperclip/templates/paperclip_migration.rb.erb +19 -0
- data/init.rb +4 -0
- data/lib/generators/paperclip/USAGE +8 -0
- data/lib/generators/paperclip/paperclip_generator.rb +33 -0
- data/lib/generators/paperclip/templates/paperclip_migration.rb.erb +19 -0
- data/lib/paperclip.rb +493 -0
- data/lib/paperclip/attachment.rb +491 -0
- data/lib/paperclip/attachment_options.rb +10 -0
- data/lib/paperclip/callback_compatibility.rb +61 -0
- data/lib/paperclip/geometry.rb +120 -0
- data/lib/paperclip/interpolations.rb +174 -0
- data/lib/paperclip/iostream.rb +45 -0
- data/lib/paperclip/matchers.rb +64 -0
- data/lib/paperclip/matchers/have_attached_file_matcher.rb +57 -0
- data/lib/paperclip/matchers/validate_attachment_content_type_matcher.rb +81 -0
- data/lib/paperclip/matchers/validate_attachment_presence_matcher.rb +54 -0
- data/lib/paperclip/matchers/validate_attachment_size_matcher.rb +95 -0
- data/lib/paperclip/missing_attachment_styles.rb +87 -0
- data/lib/paperclip/processor.rb +58 -0
- data/lib/paperclip/railtie.rb +35 -0
- data/lib/paperclip/schema.rb +39 -0
- data/lib/paperclip/storage.rb +3 -0
- data/lib/paperclip/storage/filesystem.rb +81 -0
- data/lib/paperclip/storage/fog.rb +191 -0
- data/lib/paperclip/storage/s3.rb +351 -0
- data/lib/paperclip/style.rb +103 -0
- data/lib/paperclip/thumbnail.rb +105 -0
- data/lib/paperclip/upfile.rb +64 -0
- data/lib/paperclip/url_generator.rb +64 -0
- data/lib/paperclip/version.rb +3 -0
- data/lib/tasks/paperclip.rake +101 -0
- data/paperclip.gemspec +41 -0
- data/rails/init.rb +2 -0
- data/shoulda_macros/paperclip.rb +124 -0
- data/test/attachment_options_test.rb +40 -0
- data/test/attachment_test.rb +1211 -0
- data/test/database.yml +4 -0
- data/test/fixtures/12k.png +0 -0
- data/test/fixtures/50x50.png +0 -0
- data/test/fixtures/5k.png +0 -0
- data/test/fixtures/animated.gif +0 -0
- data/test/fixtures/bad.png +1 -0
- data/test/fixtures/fog.yml +8 -0
- data/test/fixtures/s3.yml +8 -0
- data/test/fixtures/spaced file.png +0 -0
- data/test/fixtures/text.txt +1 -0
- data/test/fixtures/twopage.pdf +0 -0
- data/test/fixtures/uppercase.PNG +0 -0
- data/test/geometry_test.rb +206 -0
- data/test/helper.rb +181 -0
- data/test/integration_test.rb +652 -0
- data/test/interpolations_test.rb +219 -0
- data/test/iostream_test.rb +71 -0
- data/test/matchers/have_attached_file_matcher_test.rb +24 -0
- data/test/matchers/validate_attachment_content_type_matcher_test.rb +110 -0
- data/test/matchers/validate_attachment_presence_matcher_test.rb +47 -0
- data/test/matchers/validate_attachment_size_matcher_test.rb +72 -0
- data/test/paperclip_missing_attachment_styles_test.rb +96 -0
- data/test/paperclip_test.rb +409 -0
- data/test/processor_test.rb +10 -0
- data/test/schema_test.rb +98 -0
- data/test/storage/filesystem_test.rb +62 -0
- data/test/storage/fog_test.rb +280 -0
- data/test/storage/s3_live_test.rb +138 -0
- data/test/storage/s3_test.rb +1093 -0
- data/test/style_test.rb +215 -0
- data/test/support/mock_attachment.rb +22 -0
- data/test/support/mock_interpolator.rb +24 -0
- data/test/support/mock_model.rb +2 -0
- data/test/support/mock_url_generator_builder.rb +27 -0
- data/test/thumbnail_test.rb +396 -0
- data/test/upfile_test.rb +53 -0
- data/test/url_generator_test.rb +187 -0
- metadata +374 -0
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA1:
|
3
|
+
metadata.gz: 24dd04093b249918fb649dd1d8e559fd788644dc
|
4
|
+
data.tar.gz: c87063ee1786227fc7c1462c5237cc60d59544f2
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: 586ce2ccb867d6ac5e829092070522e65421f9199bee01056e1b4172df2481b0e3a2d10d2da983f468c3452bb9fc917611d2bf2b4b5bd3fca5af22aa7e96c7d1
|
7
|
+
data.tar.gz: 09564bed3a1aef274fc213c8e371732b156f97a5e480e557a52b3f501cc94fa78b8e04bd3fe9b659cae473e8d96ded08d598c8196b7a6dc3cc1ed7ad5370f19e
|
data/.gitignore
ADDED
data/.travis.yml
ADDED
@@ -0,0 +1,14 @@
|
|
1
|
+
rvm:
|
2
|
+
- 1.8.7
|
3
|
+
- 1.9.2
|
4
|
+
- ree
|
5
|
+
- rbx-18mode
|
6
|
+
|
7
|
+
before_script: "sudo ntpdate -ub ntp.ubuntu.com pool.ntp.org; true"
|
8
|
+
script: "bundle exec rake clean test cucumber"
|
9
|
+
|
10
|
+
gemfile:
|
11
|
+
- gemfiles/rails2.gemfile
|
12
|
+
- gemfiles/rails3.gemfile
|
13
|
+
- gemfiles/rails3_1.gemfile
|
14
|
+
- gemfiles/rails3_2.gemfile
|
data/Appraisals
ADDED
@@ -0,0 +1,20 @@
|
|
1
|
+
appraise "rails2" do
|
2
|
+
gem "rails", "~> 2.3.14"
|
3
|
+
gem "paperclip", :path => "../"
|
4
|
+
end
|
5
|
+
|
6
|
+
appraise "rails3" do
|
7
|
+
gem "rails", "~> 3.0.10"
|
8
|
+
gem "paperclip", :path => "../"
|
9
|
+
end
|
10
|
+
|
11
|
+
appraise "rails3_1" do
|
12
|
+
gem "rails", "~> 3.1.0"
|
13
|
+
gem "paperclip", :path => "../"
|
14
|
+
end
|
15
|
+
|
16
|
+
appraise "rails3_2" do
|
17
|
+
gem "rails", "~> 3.2.0"
|
18
|
+
gem "paperclip", :path => "../"
|
19
|
+
end
|
20
|
+
|
data/CONTRIBUTING.md
ADDED
@@ -0,0 +1,38 @@
|
|
1
|
+
We love pull requests. Here's a quick guide:
|
2
|
+
|
3
|
+
1. Fork the repo.
|
4
|
+
|
5
|
+
2. Run the tests. We only take pull requests with passing tests, and it's great
|
6
|
+
to know that you have a clean slate: `bundle && rake`
|
7
|
+
|
8
|
+
3. Add a test for your change. Only refactoring and documentation changes
|
9
|
+
require no new tests. If you are adding functionality or fixing a bug, we need
|
10
|
+
a test!
|
11
|
+
|
12
|
+
4. Make the test pass.
|
13
|
+
|
14
|
+
5. Push to your fork and submit a pull request.
|
15
|
+
|
16
|
+
|
17
|
+
At this point you're waiting on us. We like to at least comment on, if not
|
18
|
+
accept, pull requests within three business days (and, typically, one business
|
19
|
+
day). We may suggest some changes or improvements or alternatives.
|
20
|
+
|
21
|
+
Some things that will increase the chance that your pull request is accepted,
|
22
|
+
taken straight from the Ruby on Rails guide:
|
23
|
+
|
24
|
+
* Use Rails idioms and helpers
|
25
|
+
* Include tests that fail without your code, and pass with it
|
26
|
+
* Update the documentation, the surrounding one, examples elsewhere, guides,
|
27
|
+
whatever is affected by your contribution
|
28
|
+
|
29
|
+
Syntax:
|
30
|
+
|
31
|
+
* Two spaces, no tabs.
|
32
|
+
* No trailing whitespace. Blank lines should not have any space.
|
33
|
+
* Prefer &&/|| over and/or.
|
34
|
+
* MyClass.my_method(my_arg) not my_method( my_arg ) or my_method my_arg.
|
35
|
+
* a = b and not a=b.
|
36
|
+
* Follow the conventions you see used in the source already.
|
37
|
+
|
38
|
+
And in case we didn't emphasize it enough: we love tests!
|
data/Gemfile
ADDED
data/LICENSE
ADDED
@@ -0,0 +1,26 @@
|
|
1
|
+
|
2
|
+
LICENSE
|
3
|
+
|
4
|
+
The MIT License
|
5
|
+
|
6
|
+
Copyright (c) 2008 Jon Yurek and thoughtbot, inc.
|
7
|
+
|
8
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
9
|
+
of this software and associated documentation files (the "Software"), to deal
|
10
|
+
in the Software without restriction, including without limitation the rights
|
11
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
12
|
+
copies of the Software, and to permit persons to whom the Software is
|
13
|
+
furnished to do so, subject to the following conditions:
|
14
|
+
|
15
|
+
The above copyright notice and this permission notice shall be included in
|
16
|
+
all copies or substantial portions of the Software.
|
17
|
+
|
18
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
19
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
20
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
21
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
22
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
23
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
24
|
+
THE SOFTWARE.
|
25
|
+
|
26
|
+
|
data/NEWS
ADDED
@@ -0,0 +1,69 @@
|
|
1
|
+
New in 2.7.5:
|
2
|
+
|
3
|
+
* Feature: :s3_host_name can be a proc
|
4
|
+
|
5
|
+
New in 2.7.4:
|
6
|
+
|
7
|
+
* Feature: Allow :escape_url as an option in the defaults
|
8
|
+
* Bug fix: Correcting some PATH-based tests.
|
9
|
+
* Compatability: Cucumber tests work for Rails 3.2.8
|
10
|
+
|
11
|
+
New in 2.7.2
|
12
|
+
|
13
|
+
* Bug fix: Ensured the correct cocaine version.
|
14
|
+
* Bug fix: Fixed some tests that shouldn't have been passing.
|
15
|
+
|
16
|
+
New in 2.7.1:
|
17
|
+
|
18
|
+
* Bug fix: Fixed the problem with E2BIG errors and an ever-expanding path
|
19
|
+
|
20
|
+
New in 2.7.0:
|
21
|
+
|
22
|
+
* Bug fix: Checking the existence of a file on S3 handles all AWS errors.
|
23
|
+
* Bug fix: Clear the fingerprint when removing an attachment.
|
24
|
+
* Bug fix: Attachment size validation message reads more nicely now.
|
25
|
+
* Feature: Style names can be either symbols or strings.
|
26
|
+
* Compatibility: Support for ActiveSupport < 2.3.12.
|
27
|
+
* Compatibility: Support for Rails 3.2.
|
28
|
+
|
29
|
+
New in 2.6.0:
|
30
|
+
|
31
|
+
* Bug fix: Files are re-wound after reading.
|
32
|
+
* Feature: Remove Rails dependency from specs that need Paperclip.
|
33
|
+
* Feature: Validation matchers support conditionals.
|
34
|
+
|
35
|
+
New in 2.5.2:
|
36
|
+
|
37
|
+
* Bug fix: Can be installed on Windows.
|
38
|
+
* Feature: The Fog bucket name, authentication, and host can be determined at runtime via Proc.
|
39
|
+
* Feature: Special characters are replaced with underscores in #url and #path.
|
40
|
+
|
41
|
+
New in 2.5.1:
|
42
|
+
|
43
|
+
* Feature: After we've computed the content type, pass it to Fog.
|
44
|
+
* Feature: S3 encryption with the new :s3_server_side_encryption option.
|
45
|
+
* Feature: Works without ActiveRecord, allowing for e.g. mongo backends.
|
46
|
+
|
47
|
+
New in 2.5.0:
|
48
|
+
|
49
|
+
* Performance: Only connect to S3 when absolutely needed.
|
50
|
+
* Bug fix: STI with cached classes respect new options.
|
51
|
+
* Bug fix: conditional validations broke, and now work again.
|
52
|
+
* Feature: URL generation is now parameterized and can be changed with plugins or custom code.
|
53
|
+
* Feature: :convert_options and :source_file_options to control the ImageMagick processing.
|
54
|
+
* Performance: String geometry specifications now parse more quickly.
|
55
|
+
* Bug fix: Handle files with question marks in the filename.
|
56
|
+
* Bug fix: Don't raise an error when generating an expiring URL on an unassigned attachment.
|
57
|
+
* Bug fix: The rake task runs over all instances of an ActiveRecord model, ignoring default scopes.
|
58
|
+
* Feature: DB migration has_attached_file and drop_attached_file methods.
|
59
|
+
* Bug fix: Switch from AWS::S3 to AWS::SDK for the S3 backend.
|
60
|
+
* Bug fix: URL generator uses '?' in the URL unless it already appears and there is no prior '='.
|
61
|
+
* Bug fix: Always convert the content type to a string before stripping blanks.
|
62
|
+
* Feature: The :keep_old_files option preserves the files in storage even when the attachment is cleared or changed.
|
63
|
+
* Performance: Optimize Fog's public_url access by avoiding it when possible.
|
64
|
+
* Bug fix: Avoid a runtime error when generating the ID partition for an unsaved attachment.
|
65
|
+
* Performance: Do not calculate the fingerprint if it is never persisted.
|
66
|
+
* Bug fix: Process the :original style before all others, in case of a dependency.
|
67
|
+
* Feature: S3 headers can be set at runtime by passing a proc object as the value.
|
68
|
+
* Bug fix: Generating missing attachment styles for a model which has had its attachment changed should not raise.
|
69
|
+
* Bug fix: Do not collide with the built-in Ruby hashing method.
|
data/README.md
ADDED
@@ -0,0 +1,444 @@
|
|
1
|
+
Paperclip
|
2
|
+
=========
|
3
|
+
|
4
|
+
[![Build Status](https://secure.travis-ci.org/thoughtbot/paperclip.png?branch=master)](http://travis-ci.org/thoughtbot/paperclip) [![Dependency Status](https://gemnasium.com/thoughtbot/paperclip.png?travis)](https://gemnasium.com/thoughtbot/paperclip)
|
5
|
+
|
6
|
+
Paperclip is intended as an easy file attachment library for Active Record. The
|
7
|
+
intent behind it was to keep setup as easy as possible and to treat files as
|
8
|
+
much like other attributes as possible. This means they aren't saved to their
|
9
|
+
final locations on disk, nor are they deleted if set to nil, until
|
10
|
+
ActiveRecord::Base#save is called. It manages validations based on size and
|
11
|
+
presence, if required. It can transform its assigned image into thumbnails if
|
12
|
+
needed, and the prerequisites are as simple as installing ImageMagick (which,
|
13
|
+
for most modern Unix-based systems, is as easy as installing the right
|
14
|
+
packages). Attached files are saved to the filesystem and referenced in the
|
15
|
+
browser by an easily understandable specification, which has sensible and
|
16
|
+
useful defaults.
|
17
|
+
|
18
|
+
See the documentation for `has_attached_file` in [`Paperclip::ClassMethods`](http://rubydoc.info/gems/paperclip/Paperclip/ClassMethods) for
|
19
|
+
more detailed options.
|
20
|
+
|
21
|
+
The complete [RDoc](http://rdoc.info/gems/paperclip) is online.
|
22
|
+
|
23
|
+
|
24
|
+
Requirements
|
25
|
+
------------
|
26
|
+
|
27
|
+
ImageMagick must be installed and Paperclip must have access to it. To ensure
|
28
|
+
that it does, on your command line, run `which convert` (one of the ImageMagick
|
29
|
+
utilities). This will give you the path where that utility is installed. For
|
30
|
+
example, it might return `/usr/local/bin/convert`.
|
31
|
+
|
32
|
+
Then, in your environment config file, let Paperclip know to look there by adding that
|
33
|
+
directory to its path.
|
34
|
+
|
35
|
+
In development mode, you might add this line to `config/environments/development.rb)`:
|
36
|
+
|
37
|
+
Paperclip.options[:command_path] = "/usr/local/bin/"
|
38
|
+
|
39
|
+
If you're on Mac OS X, you'll want to run the following with Homebrew:
|
40
|
+
|
41
|
+
brew install imagemagick
|
42
|
+
|
43
|
+
If you are dealing with pdf uploads or running the test suite, you'll also need
|
44
|
+
GhostScript to be installed. On Mac OS X, you can also install that using Homebrew:
|
45
|
+
|
46
|
+
brew install gs
|
47
|
+
|
48
|
+
|
49
|
+
Installation
|
50
|
+
------------
|
51
|
+
|
52
|
+
Paperclip is distributed as a gem, which is how it should be used in your app. It's
|
53
|
+
technically still installable as a plugin, but that's discouraged, as Rails plays
|
54
|
+
well with gems.
|
55
|
+
|
56
|
+
Include the gem in your Gemfile:
|
57
|
+
|
58
|
+
gem "paperclip", "~> 2.0"
|
59
|
+
|
60
|
+
Or, if you want to get the latest, you can get master from the main paperclip repository:
|
61
|
+
|
62
|
+
gem "paperclip", :git => "git://github.com/thoughtbot/paperclip.git"
|
63
|
+
|
64
|
+
If you're trying to use features that don't seem to be in the latest released gem, but are
|
65
|
+
mentioned in this README, then you probably need to specify the master branch if you want to
|
66
|
+
use them. This README is probably ahead of the latest released version, if you're reading it
|
67
|
+
on GitHub.
|
68
|
+
|
69
|
+
Anyway, if you don't use Bundler (though you probably should, even in Rails 2), with config.gem
|
70
|
+
|
71
|
+
# In config/environment.rb
|
72
|
+
...
|
73
|
+
Rails::Initializer.run do |config|
|
74
|
+
...
|
75
|
+
config.gem "paperclip", :version => "~> 2.4"
|
76
|
+
...
|
77
|
+
end
|
78
|
+
|
79
|
+
For Non-Rails usage:
|
80
|
+
|
81
|
+
class ModuleName < ActiveRecord::Base
|
82
|
+
include Paperclip::Glue
|
83
|
+
...
|
84
|
+
end
|
85
|
+
|
86
|
+
Quick Start
|
87
|
+
-----------
|
88
|
+
|
89
|
+
In your model:
|
90
|
+
|
91
|
+
class User < ActiveRecord::Base
|
92
|
+
has_attached_file :avatar, :styles => { :medium => "300x300>", :thumb => "100x100>" }
|
93
|
+
end
|
94
|
+
|
95
|
+
In your migrations:
|
96
|
+
|
97
|
+
class AddAvatarColumnsToUser < ActiveRecord::Migration
|
98
|
+
def self.up
|
99
|
+
change_table :users do |t|
|
100
|
+
t.has_attached_file :avatar
|
101
|
+
end
|
102
|
+
end
|
103
|
+
|
104
|
+
def self.down
|
105
|
+
drop_attached_file :users, :avatar
|
106
|
+
end
|
107
|
+
end
|
108
|
+
|
109
|
+
In your edit and new views:
|
110
|
+
|
111
|
+
<%= form_for :user, @user, :url => user_path, :html => { :multipart => true } do |form| %>
|
112
|
+
<%= form.file_field :avatar %>
|
113
|
+
<% end %>
|
114
|
+
|
115
|
+
In your controller:
|
116
|
+
|
117
|
+
def create
|
118
|
+
@user = User.create( params[:user] )
|
119
|
+
end
|
120
|
+
|
121
|
+
In your show view:
|
122
|
+
|
123
|
+
<%= image_tag @user.avatar.url %>
|
124
|
+
<%= image_tag @user.avatar.url(:medium) %>
|
125
|
+
<%= image_tag @user.avatar.url(:thumb) %>
|
126
|
+
|
127
|
+
To detach a file, simply set the attribute to `nil`:
|
128
|
+
|
129
|
+
@user.avatar = nil
|
130
|
+
@user.save
|
131
|
+
|
132
|
+
Usage
|
133
|
+
-----
|
134
|
+
|
135
|
+
The basics of paperclip are quite simple: Declare that your model has an
|
136
|
+
attachment with the `has_attached_file` method, and give it a name.
|
137
|
+
|
138
|
+
Paperclip will wrap up up to four attributes (all prefixed with that attachment's name,
|
139
|
+
so you can have multiple attachments per model if you wish) and give them a
|
140
|
+
friendly front end. These attributes are:
|
141
|
+
|
142
|
+
* `<attachment>_file_name`
|
143
|
+
* `<attachment>_file_size`
|
144
|
+
* `<attachment>_content_type`
|
145
|
+
* `<attachment>_updated_at`
|
146
|
+
|
147
|
+
By default, only `<attachment>_file_name` is required for paperclip to operate.
|
148
|
+
You'll need to add `<attachment>_content_type` in case you want to use content type
|
149
|
+
validation.
|
150
|
+
|
151
|
+
More information about the options to `has_attached_file` is available in the
|
152
|
+
documentation of [`Paperclip::ClassMethods`](http://rubydoc.info/gems/paperclip/Paperclip/ClassMethods).
|
153
|
+
|
154
|
+
For validations, attachments can be validated with these Paperclip's validation methods:
|
155
|
+
|
156
|
+
* `validates_attachment_presence`
|
157
|
+
* `validates_attachment_content_type`
|
158
|
+
* `validates_attachment_size`
|
159
|
+
|
160
|
+
Storage
|
161
|
+
-------
|
162
|
+
|
163
|
+
The files that are assigned as attachments are, by default, placed in the
|
164
|
+
directory specified by the `:path` option to `has_attached_file`. By default, this
|
165
|
+
location is `:rails_root/public/system/:attachment/:id/:style/:filename`. This
|
166
|
+
location was chosen because on standard Capistrano deployments, the
|
167
|
+
`public/system` directory is symlinked to the app's shared directory, meaning it
|
168
|
+
will survive between deployments. For example, using that `:path`, you may have a
|
169
|
+
file at
|
170
|
+
|
171
|
+
/data/myapp/releases/20081229172410/public/system/avatars/13/small/my_pic.png
|
172
|
+
|
173
|
+
_**NOTE**: This is a change from previous versions of Paperclip, but is overall a
|
174
|
+
safer choice for the default file store._
|
175
|
+
|
176
|
+
You may also choose to store your files using Amazon's S3 service. To do so, include
|
177
|
+
the `aws-sdk` gem in your Gemfile:
|
178
|
+
|
179
|
+
gem 'aws-sdk', '~> 1.3.4'
|
180
|
+
|
181
|
+
And then you can specify using S3 from `has_attached_file`.
|
182
|
+
You can find more information about configuring and using S3 storage in
|
183
|
+
[the `Paperclip::Storage::S3` documentation](http://rubydoc.info/gems/paperclip/Paperclip/Storage/S3).
|
184
|
+
|
185
|
+
Files on the local filesystem (and in the Rails app's public directory) will be
|
186
|
+
available to the internet at large. If you require access control, it's
|
187
|
+
possible to place your files in a different location. You will need to change
|
188
|
+
both the `:path` and `:url` options in order to make sure the files are unavailable
|
189
|
+
to the public. Both `:path` and `:url` allow the same set of interpolated
|
190
|
+
variables.
|
191
|
+
|
192
|
+
Post Processing
|
193
|
+
---------------
|
194
|
+
|
195
|
+
Paperclip supports an extensible selection of post-processors. When you define
|
196
|
+
a set of styles for an attachment, by default it is expected that those
|
197
|
+
"styles" are actually "thumbnails". However, you can do much more than just
|
198
|
+
thumbnail images. By defining a subclass of Paperclip::Processor, you can
|
199
|
+
perform any processing you want on the files that are attached. Any file in
|
200
|
+
your Rails app's lib/paperclip\_processors directory is automatically loaded by
|
201
|
+
paperclip, allowing you to easily define custom processors. You can specify a
|
202
|
+
processor with the :processors option to has\_attached\_file:
|
203
|
+
|
204
|
+
has_attached\_file :scan, :styles => { :text => { :quality => :better } },
|
205
|
+
:processors => [:ocr]
|
206
|
+
|
207
|
+
This would load the hypothetical class Paperclip::Ocr, which would have the
|
208
|
+
hash "{ :quality => :better }" passed to it along with the uploaded file. For
|
209
|
+
more information about defining processors, see Paperclip::Processor.
|
210
|
+
|
211
|
+
The default processor is Paperclip::Thumbnail. For backwards compatability
|
212
|
+
reasons, you can pass a single geometry string or an array containing a
|
213
|
+
geometry and a format, which the file will be converted to, like so:
|
214
|
+
|
215
|
+
has_attached_file :avatar, :styles => { :thumb => ["32x32#", :png] }
|
216
|
+
|
217
|
+
This will convert the "thumb" style to a 32x32 square in png format, regardless
|
218
|
+
of what was uploaded. If the format is not specified, it is kept the same (i.e.
|
219
|
+
jpgs will remain jpgs). For more information on the accepted style formats, see
|
220
|
+
[http://www.imagemagick.org/script/command-line-processing.php#geometry](here).
|
221
|
+
|
222
|
+
Multiple processors can be specified, and they will be invoked in the order
|
223
|
+
they are defined in the :processors array. Each successive processor will
|
224
|
+
be given the result of the previous processor's execution. All processors will
|
225
|
+
receive the same parameters, which are what you define in the :styles hash.
|
226
|
+
For example, assuming we had this definition:
|
227
|
+
|
228
|
+
has_attached_file :scan, :styles => { :text => { :quality => :better } },
|
229
|
+
:processors => [:rotator, :ocr]
|
230
|
+
|
231
|
+
then both the :rotator processor and the :ocr processor would receive the
|
232
|
+
options "{ :quality => :better }". This parameter may not mean anything to one
|
233
|
+
or more or the processors, and they are expected to ignore it.
|
234
|
+
|
235
|
+
_NOTE: Because processors operate by turning the original attachment into the
|
236
|
+
styles, no processors will be run if there are no styles defined._
|
237
|
+
|
238
|
+
If you're interested in caching your thumbnail's width, height and size in the
|
239
|
+
database, take a look at the [paperclip-meta](https://github.com/y8/paperclip-meta) gem.
|
240
|
+
|
241
|
+
Also, if you're interested in generating the thumbnail on-the-fly, you might want
|
242
|
+
to look into the [attachment_on_the_fly](https://github.com/drpentode/Attachment-on-the-Fly) gem.
|
243
|
+
|
244
|
+
Events
|
245
|
+
------
|
246
|
+
|
247
|
+
Before and after the Post Processing step, Paperclip calls back to the model
|
248
|
+
with a few callbacks, allowing the model to change or cancel the processing
|
249
|
+
step. The callbacks are `before_post_process` and `after_post_process` (which
|
250
|
+
are called before and after the processing of each attachment), and the
|
251
|
+
attachment-specific `before_<attachment>_post_process` and
|
252
|
+
`after_<attachment>_post_process`. The callbacks are intended to be as close to
|
253
|
+
normal ActiveRecord callbacks as possible, so if you return false (specifically
|
254
|
+
\- returning nil is not the same) in a before\_ filter, the post processing step
|
255
|
+
will halt. Returning false in an after\_ filter will not halt anything, but you
|
256
|
+
can access the model and the attachment if necessary.
|
257
|
+
|
258
|
+
_NOTE: Post processing will not even *start* if the attachment is not valid
|
259
|
+
according to the validations. Your callbacks and processors will *only* be
|
260
|
+
called with valid attachments._
|
261
|
+
|
262
|
+
URI Obfuscation
|
263
|
+
---------------
|
264
|
+
|
265
|
+
Paperclip has an interpolation called `:hash` for obfuscating filenames of
|
266
|
+
publicly-available files.
|
267
|
+
|
268
|
+
Example Usage:
|
269
|
+
|
270
|
+
has_attached_file :avatar, {
|
271
|
+
:url => "/system/:hash.:extension",
|
272
|
+
:hash_secret => "longSecretString"
|
273
|
+
}
|
274
|
+
|
275
|
+
|
276
|
+
The `:hash` interpolation will be replaced with a unique hash made up of whatever
|
277
|
+
is specified in `:hash_data`. The default value for `:hash_data` is `":class/:attachment/:id/:style/:updated_at"`.
|
278
|
+
|
279
|
+
`:hash_secret` is required, an exception will be raised if `:hash` is used without `:hash_secret` present.
|
280
|
+
|
281
|
+
For more on this feature read the author's own explanation. [https://github.com/thoughtbot/paperclip/pull/416](https://github.com/thoughtbot/paperclip/pull/416)
|
282
|
+
|
283
|
+
MD5 Checksum / Fingerprint
|
284
|
+
-------
|
285
|
+
|
286
|
+
A MD5 checksum of the original file assigned will be placed in the model if it
|
287
|
+
has an attribute named fingerprint. Following the user model migration example
|
288
|
+
above, the migration would look like the following.
|
289
|
+
|
290
|
+
class AddAvatarFingerprintColumnToUser < ActiveRecord::Migration
|
291
|
+
def self.up
|
292
|
+
add_column :users, :avatar_fingerprint, :string
|
293
|
+
end
|
294
|
+
|
295
|
+
def self.down
|
296
|
+
remove_column :users, :avatar_fingerprint
|
297
|
+
end
|
298
|
+
end
|
299
|
+
|
300
|
+
Custom Attachment Processors
|
301
|
+
-------
|
302
|
+
|
303
|
+
Custom attachment processors can be implemented and their only requirement is
|
304
|
+
to inherit from `Paperclip::Processor` (see `lib/paperclip/processor.rb`).
|
305
|
+
For example, when `:styles` are specified for an image attachment, the
|
306
|
+
thumbnail processor (see `lib/paperclip/thumbnail.rb`) is loaded without having
|
307
|
+
to specify it as a `:processor` parameter to `has_attached_file`. When any
|
308
|
+
other processor is defined it must be called out in the `:processors`
|
309
|
+
parameter if it is to be applied to the attachment. The thumbnail processor
|
310
|
+
uses the imagemagick `convert` command to do the work of resizing image
|
311
|
+
thumbnails. It would be easy to create a custom processor that watermarks
|
312
|
+
an image using imagemagick's `composite` command. Following the
|
313
|
+
implementation pattern of the thumbnail processor would be a way to implement a
|
314
|
+
watermark processor. All kinds of attachment processors can be created;
|
315
|
+
a few utility examples would be compression and encryption processors.
|
316
|
+
|
317
|
+
|
318
|
+
Dynamic Configuration
|
319
|
+
---------------------
|
320
|
+
|
321
|
+
Callable objects (lambdas, Procs) can be used in a number of places for dynamic
|
322
|
+
configuration throughout Paperclip. This strategy exists in a number of
|
323
|
+
components of the library but is most significant in the possibilities for
|
324
|
+
allowing custom styles and processors to be applied for specific model
|
325
|
+
instances, rather than applying defined styles and processors across all
|
326
|
+
instances.
|
327
|
+
|
328
|
+
Dynamic Styles:
|
329
|
+
|
330
|
+
Imagine a user model that had different styles based on the role of the user.
|
331
|
+
Perhaps some users are bosses (e.g. a User model instance responds to #boss?)
|
332
|
+
and merit a bigger avatar thumbnail than regular users. The configuration to
|
333
|
+
determine what style parameters are to be used based on the user role might
|
334
|
+
look as follows where a boss will receive a `300x300` thumbnail otherwise a
|
335
|
+
`100x100` thumbnail will be created.
|
336
|
+
|
337
|
+
class User < ActiveRecord::Base
|
338
|
+
has_attached_file :avatar, :styles => lambda { |attachment| { :thumb => (attachment.instance.boss? ? "300x300>" : "100x100>") }
|
339
|
+
end
|
340
|
+
|
341
|
+
Dynamic Processors:
|
342
|
+
|
343
|
+
Another contrived example is a user model that is aware of which file processors
|
344
|
+
should be applied to it (beyond the implied `thumbnail` processor invoked when
|
345
|
+
`:styles` are defined). Perhaps we have a watermark processor available and it is
|
346
|
+
only used on the avatars of certain models. The configuration for this might be
|
347
|
+
where the instance is queried for which processors should be applied to it.
|
348
|
+
Presumably some users might return `[:thumbnail, :watermark]` for its
|
349
|
+
processors, where a defined `watermark` processor is invoked after the
|
350
|
+
`thumbnail` processor already defined by Paperclip.
|
351
|
+
|
352
|
+
class User < ActiveRecord::Base
|
353
|
+
has_attached_file :avatar, :processors => lambda { |instance| instance.processors }
|
354
|
+
attr_accessor :watermark
|
355
|
+
end
|
356
|
+
|
357
|
+
Deploy
|
358
|
+
------
|
359
|
+
|
360
|
+
Paperclip is aware of new attachment styles you have added in previous deploy. The only thing you should do after each deployment is to call
|
361
|
+
`rake paperclip:refresh:missing_styles`. It will store current attachment styles in `RAILS_ROOT/public/system/paperclip_attachments.yml`
|
362
|
+
by default. You can change it by:
|
363
|
+
|
364
|
+
Paperclip.registered_attachments_styles_path = '/tmp/config/paperclip_attachments.yml'
|
365
|
+
|
366
|
+
Here is an example for Capistrano:
|
367
|
+
|
368
|
+
namespace :deploy do
|
369
|
+
desc "build missing paperclip styles"
|
370
|
+
task :build_missing_paperclip_styles, :roles => :app do
|
371
|
+
run "cd #{release_path}; RAILS_ENV=production bundle exec rake paperclip:refresh:missing_styles"
|
372
|
+
end
|
373
|
+
end
|
374
|
+
|
375
|
+
after("deploy:update_code", "deploy:build_missing_paperclip_styles")
|
376
|
+
|
377
|
+
Now you don't have to remember to refresh thumbnails in production everytime you add new style.
|
378
|
+
Unfortunately it does not work with dynamic styles - it just ignores them.
|
379
|
+
|
380
|
+
If you already have working app and don't want `rake paperclip:refresh:missing_styles` to refresh old pictures, you need to tell
|
381
|
+
Paperclip about existing styles. Simply create paperclip\_attachments.yml file by hand. For example:
|
382
|
+
|
383
|
+
class User < ActiveRecord::Base
|
384
|
+
has_attached_file :avatar, :styles => {:thumb => 'x100', :croppable => '600x600>', :big => '1000x1000>'}
|
385
|
+
end
|
386
|
+
|
387
|
+
class Book < ActiveRecord::Base
|
388
|
+
has_attached_file :cover, :styles => {:small => 'x100', :large => '1000x1000>'}
|
389
|
+
has_attached_file :sample, :styles => {:thumb => 'x100'}
|
390
|
+
end
|
391
|
+
|
392
|
+
Then in `RAILS_ROOT/public/system/paperclip_attachments.yml`:
|
393
|
+
|
394
|
+
---
|
395
|
+
:User:
|
396
|
+
:avatar:
|
397
|
+
- :thumb
|
398
|
+
- :croppable
|
399
|
+
- :big
|
400
|
+
:Book:
|
401
|
+
:cover:
|
402
|
+
- :small
|
403
|
+
- :large
|
404
|
+
:sample:
|
405
|
+
- :thumb
|
406
|
+
|
407
|
+
Testing
|
408
|
+
-------
|
409
|
+
|
410
|
+
Paperclip provides rspec-compatible matchers for testing attachments. See the
|
411
|
+
documentation on [Paperclip::Shoulda::Matchers](http://rubydoc.info/gems/paperclip/Paperclip/Shoulda/Matchers)
|
412
|
+
for more information.
|
413
|
+
|
414
|
+
Contributing
|
415
|
+
------------
|
416
|
+
|
417
|
+
If you'd like to contribute a feature or bugfix: Thanks! To make sure your
|
418
|
+
fix/feature has a high chance of being included, please read the following
|
419
|
+
guidelines:
|
420
|
+
|
421
|
+
1. Ask on the mailing list[http://groups.google.com/group/paperclip-plugin], or
|
422
|
+
post a new GitHub Issue[http://github.com/thoughtbot/paperclip/issues].
|
423
|
+
2. Make sure there are tests! We will not accept any patch that is not tested.
|
424
|
+
It's a rare time when explicit tests aren't needed. If you have questions
|
425
|
+
about writing tests for paperclip, please ask the mailing list.
|
426
|
+
|
427
|
+
Please see CONTRIBUTING.md for details.
|
428
|
+
|
429
|
+
Credits
|
430
|
+
-------
|
431
|
+
|
432
|
+
![thoughtbot](http://thoughtbot.com/images/tm/logo.png)
|
433
|
+
|
434
|
+
Paperclip is maintained and funded by [thoughtbot, inc](http://thoughtbot.com/community)
|
435
|
+
|
436
|
+
Thank you to all [the contributors](https://github.com/thoughtbot/paperclip/contributors)!
|
437
|
+
|
438
|
+
The names and logos for thoughtbot are trademarks of thoughtbot, inc.
|
439
|
+
|
440
|
+
License
|
441
|
+
-------
|
442
|
+
|
443
|
+
Paperclip is Copyright © 2008-2011 thoughtbot. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.
|
444
|
+
|