Skip to content
This repository
Newer
Older
100644 227 lines (209 sloc) 10.431 kb
110df00f »
2007-08-19 Extensive documentation, adding ability to crop thumbnails.
1 # Paperclip allows file attachments that are stored in the filesystem. All graphical
2 # transformations are done using the Graphics/ImageMagick command line utilities and
d3af7c6e »
2008-03-18 Doc change
3 # are stored in Tempfiles until the record is saved. Paperclip does not require a
5494e3cf »
2007-11-17 Docs and some splitting up of files because the single one was annoying.
4 # separate model for storing the attachment's information, instead adding a few simple
5 # columns to your table.
110df00f »
2007-08-19 Extensive documentation, adding ability to crop thumbnails.
6 #
7 # Author:: Jon Yurek
98966791 »
2011-06-28 changed copyright
8 # Copyright:: Copyright (c) 2008-2011 thoughtbot, inc.
61d8253b »
2008-04-16 Clarified the license.
9 # License:: MIT License (http://www.opensource.org/licenses/mit-license.php)
110df00f »
2007-08-19 Extensive documentation, adding ability to crop thumbnails.
10 #
d68a9421 »
2007-11-09 Re-refactoring
11 # Paperclip defines an attachment as any file, though it makes special considerations
12 # for image files. You can declare that a model has an attached file with the
13 # +has_attached_file+ method:
14 #
15 # class User < ActiveRecord::Base
c77ba25e »
2008-03-12 Fixed up some documentation
16 # has_attached_file :avatar, :styles => { :thumb => "100x100" }
d68a9421 »
2007-11-09 Re-refactoring
17 # end
18 #
19 # user = User.new
20 # user.avatar = params[:user][:avatar]
21 # user.avatar.url
22 # # => "/users/avatars/4/original_me.jpg"
23 # user.avatar.url(:thumb)
24 # # => "/users/avatars/4/thumb_me.jpg"
25 #
110df00f »
2007-08-19 Extensive documentation, adding ability to crop thumbnails.
26 # See the +has_attached_file+ documentation for more details.
5494e3cf »
2007-11-17 Docs and some splitting up of files because the single one was annoying.
27
d6ebd321 »
2009-09-08 Run S3 configuration file through ERB before parsing the YAML.
28 require 'erb'
2cdeb39a »
2010-06-10 Added fingerprinting support
29 require 'digest'
349a466f »
2008-04-01 required tempfile
30 require 'tempfile'
bf33af34 »
2010-06-08 put version in its own file
31 require 'paperclip/version'
2784b380 »
2008-03-18 Huge refactoring.
32 require 'paperclip/geometry'
f1118c6b »
2008-12-24 Added Paperclip::Processor as a necessary superclass of Thumbnail (an…
33 require 'paperclip/processor'
8a758c27 »
2012-03-16 Make the test pass on JRuby
34 require 'paperclip/tempfile'
2784b380 »
2008-03-18 Huge refactoring.
35 require 'paperclip/thumbnail'
f22d78f3 »
2009-05-06 Moved interpolations out of attachment
36 require 'paperclip/interpolations'
073152ee »
2012-06-08 Abstract the Tempfile generation into a factory
37 require 'paperclip/tempfile_factory'
7a42e651 »
2009-12-18 styles encapsulated, to delay calling of procs until context is usefu…
38 require 'paperclip/style'
2784b380 »
2008-03-18 Huge refactoring.
39 require 'paperclip/attachment'
5f8140d1 »
2012-02-03 passing AttachmentOptions instance instead of hash to Attachment.new
40 require 'paperclip/attachment_options'
5e4dcb4d »
2010-10-06 Don't require storage module files directly.
41 require 'paperclip/storage'
5232b192 »
2012-03-06 Remove Rails 2 support from Paperclip
42 require 'paperclip/callbacks'
f407412f »
2012-06-15 Adds a class for managing content type detection
43 require 'paperclip/content_type_detector'
5232b192 »
2012-03-06 Remove Rails 2 support from Paperclip
44 require 'paperclip/glue'
03f777f8 »
2012-03-16 Extract some modules from Paperclip.rb
45 require 'paperclip/errors'
3ae7a3e8 »
2011-08-25 Tracking new attachment styles with a Rake task to refresh them
46 require 'paperclip/missing_attachment_styles'
03f777f8 »
2012-03-16 Extract some modules from Paperclip.rb
47 require 'paperclip/validators'
48 require 'paperclip/instance_methods'
49 require 'paperclip/logger'
50 require 'paperclip/helpers'
89c8d117 »
2011-12-02 Adds IO adapters to abstract the things that can be assigned.
51 require 'mime/types'
6b6ce9ed »
2011-08-23 Don't hardcode the logger in paperclip.rb
52 require 'logger'
f0d15d91 »
2011-05-19 Extracted the CommandLine class into the Cocaine gem.
53 require 'cocaine'
5494e3cf »
2007-11-17 Docs and some splitting up of files because the single one was annoying.
54
47db66f2 »
2012-04-24 Do not require railtie unless Rails is defined
55 require 'paperclip/railtie' if defined?(Rails)
56
5fdf9640 »
2008-05-15 Updated documentation.
57 # The base module that gets included in ActiveRecord::Base. See the
58 # documentation for Paperclip::ClassMethods for more useful information.
d68a9421 »
2007-11-09 Re-refactoring
59 module Paperclip
03f777f8 »
2012-03-16 Extract some modules from Paperclip.rb
60 extend Helpers
61 extend Logger
62 extend ProcessorHelpers
63
64 # Provides configurability to Paperclip. The options available are:
65 # * whiny: Will raise an error if Paperclip cannot process thumbnails of
66 # an uploaded image. Defaults to true.
67 # * log: Logs progress to the Rails log. Uses ActiveRecord's logger, so honors
68 # log levels, etc. Defaults to true.
69 # * command_path: Defines the path at which to find the command line
70 # programs if they are not visible to Rails the system's search path. Defaults to
71 # nil, which uses the first executable found in the user's search path.
72 def self.options
73 @options ||= {
74 :whiny => true,
75 :image_magick_path => nil,
76 :command_path => nil,
77 :log => true,
78 :log_command => true,
79 :swallow_stderr => true
80 }
3eb7844c »
2009-05-08 Added :url and :timestamp interpolations.
81 end
c40d947e »
2008-05-07 Changed ENOENT to NotIdentifiedByImageMagick, which should work with …
82
78cfebd5 »
2012-03-30 Changes from merging with master/3.0
83 def self.io_adapters=(new_registry)
84 @io_adapters = new_registry
85 end
86
87 def self.io_adapters
88 @io_adapters ||= Paperclip::AdapterRegistry.new
89 end
90
d68a9421 »
2007-11-09 Re-refactoring
91 module ClassMethods
5494e3cf »
2007-11-17 Docs and some splitting up of files because the single one was annoying.
92 # +has_attached_file+ gives the class it is called on an attribute that maps to a file. This
3be55fc8 »
2010-06-07 Clean up whitespace
93 # is typically a file stored somewhere on the filesystem and has been uploaded by a user.
2784b380 »
2008-03-18 Huge refactoring.
94 # The attribute returns a Paperclip::Attachment object which handles the management of
3be55fc8 »
2010-06-07 Clean up whitespace
95 # that file. The intent is to make the attachment as much like a normal attribute. The
96 # thumbnails will be created when the new file is assigned, but they will *not* be saved
97 # until +save+ is called on the record. Likewise, if the attribute is set to +nil+ is
98 # called on it, the attachment will *not* be deleted until +save+ is called. See the
99 # Paperclip::Attachment documentation for more specifics. There are a number of options
2784b380 »
2008-03-18 Huge refactoring.
100 # you can set to change the behavior of a Paperclip attachment:
101 # * +url+: The full URL of where the attachment is publically accessible. This can just
102 # as easily point to a directory served directly through Apache as it can to an action
103 # that can control permissions. You can specify the full domain and path, but usually
3be55fc8 »
2010-06-07 Clean up whitespace
104 # just an absolute path is sufficient. The leading slash *must* be included manually for
105 # absolute paths. The default value is
cf8f76d8 »
2012-07-03 Update Paperclip's default URL in documentation
106 # "/system/:class/:attachment/:id_partition/:style/:filename". See
5494e3cf »
2007-11-17 Docs and some splitting up of files because the single one was annoying.
107 # Paperclip::Attachment#interpolate for more information on variable interpolaton.
6539e540 »
2009-05-10 Updated documentation and gemspec for 2.2.9
108 # :url => "/:class/:attachment/:id/:style_:filename"
5494e3cf »
2007-11-17 Docs and some splitting up of files because the single one was annoying.
109 # :url => "http://some.other.host/stuff/:class/:id_:extension"
3be55fc8 »
2010-06-07 Clean up whitespace
110 # * +default_url+: The URL that will be returned if there is no attachment assigned.
111 # This field is interpolated just as the url is. The default value is
e345764e »
2008-12-29 Updated documentation. Also changed the defaults of :path and :url to…
112 # "/:attachment/:style/missing.png"
e35fa9eb »
2008-03-20 Fixed bug with default_url
113 # has_attached_file :avatar, :default_url => "/images/default_:style_avatar.png"
5494e3cf »
2007-11-17 Docs and some splitting up of files because the single one was annoying.
114 # User.new.avatar_url(:small) # => "/images/default_small_avatar.png"
3be55fc8 »
2010-06-07 Clean up whitespace
115 # * +styles+: A hash of thumbnail styles and their geometries. You can find more about
116 # geometry strings at the ImageMagick website
2784b380 »
2008-03-18 Huge refactoring.
117 # (http://www.imagemagick.org/script/command-line-options.php#resize). Paperclip
3be55fc8 »
2010-06-07 Clean up whitespace
118 # also adds the "#" option (e.g. "50x50#"), which will resize the image to fit maximally
119 # inside the dimensions and then crop the rest off (weighted at the center). The
2784b380 »
2008-03-18 Huge refactoring.
120 # default value is to generate no thumbnails.
3be55fc8 »
2010-06-07 Clean up whitespace
121 # * +default_style+: The thumbnail style that will be used by default URLs.
2784b380 »
2008-03-18 Huge refactoring.
122 # Defaults to +original+.
c77ba25e »
2008-03-12 Fixed up some documentation
123 # has_attached_file :avatar, :styles => { :normal => "100x100#" },
5494e3cf »
2007-11-17 Docs and some splitting up of files because the single one was annoying.
124 # :default_style => :normal
125 # user.avatar.url # => "/avatars/23/normal_me.png"
345ec743 »
2011-12-13 Add 'keep_old_files' option.
126 # * +keep_old_files+: Keep the existing attachment files (original + resized) from
127 # being automatically deleted when an attachment is cleared or updated.
128 # Defaults to +false+.#
6539e540 »
2009-05-10 Updated documentation and gemspec for 2.2.9
129 # * +whiny+: Will raise an error if Paperclip cannot post_process an uploaded file due
3be55fc8 »
2010-06-07 Clean up whitespace
130 # to a command line error. This will override the global setting for this attachment.
defd4259 »
2012-03-02 Remove all the deprecated method
131 # Defaults to true.
457c0cd5 »
2008-09-12 Documentation for convert_options
132 # * +convert_options+: When creating thumbnails, use this free-form options
724cc7e1 »
2010-04-30 Changed Paperclip.run to take an array. Quotes this array for shell s…
133 # array to pass in various convert command options. Typical options are "-strip" to
8b41b3fc »
2008-08-07 Add thumbnail_convert_options documentation to has_attached_file doc.
134 # remove all Exif data from the image (save space for thumbnails and avatars) or
135 # "-depth 8" to specify the bit depth of the resulting conversion. See ImageMagick
136 # convert documentation for more options: (http://www.imagemagick.org/script/convert.php)
457c0cd5 »
2008-09-12 Documentation for convert_options
137 # Note that this option takes a hash of options, each of which correspond to the style
138 # of thumbnail being generated. You can also specify :all as a key, which will apply
139 # to all of the thumbnails being generated. If you specify options for the :original,
140 # it would be best if you did not specify destructive options, as the intent of keeping
7dbdb4c5 »
2008-10-10 Fix typo in convert_options documentation.
141 # the original around is to regenerate all the thumbnails when requirements change.
457c0cd5 »
2008-09-12 Documentation for convert_options
142 # has_attached_file :avatar, :styles => { :large => "300x300", :negative => "100x100" }
143 # :convert_options => {
144 # :all => "-strip",
145 # :negative => "-negate"
146 # }
6539e540 »
2009-05-10 Updated documentation and gemspec for 2.2.9
147 # NOTE: While not deprecated yet, it is not recommended to specify options this way.
148 # It is recommended that :convert_options option be included in the hash passed to each
35988dbd »
2011-06-24 Compatability => Compatibility :+1+
149 # :styles for compatibility with future versions.
724cc7e1 »
2010-04-30 Changed Paperclip.run to take an array. Quotes this array for shell s…
150 # NOTE: Strings supplied to :convert_options are split on space in order to undergo
151 # shell quoting for safety. If your options require a space, please pre-split them
152 # and pass an array to :convert_options instead.
5fdf9640 »
2008-05-15 Updated documentation.
153 # * +storage+: Chooses the storage backend where the files will be stored. The current
7b70fa48 »
2012-01-05 Mention Fog storage backend
154 # choices are :filesystem, :fog and :s3. The default is :filesystem. Make sure you read the
155 # documentation for Paperclip::Storage::Filesystem, Paperclip::Storage::Fog and Paperclip::Storage::S3
5fdf9640 »
2008-05-15 Updated documentation.
156 # for backend-specific options.
1738f3c8 »
2011-09-23 Add some more documentation for passing symbol to :url, :default_url,…
157 #
7b70fa48 »
2012-01-05 Mention Fog storage backend
158 # It's also possible for you to dynamically define your interpolation string for :url,
1738f3c8 »
2011-09-23 Add some more documentation for passing symbol to :url, :default_url,…
159 # :default_url, and :path in your model by passing a method name as a symbol as a argument
160 # for your has_attached_file definition:
161 #
162 # class Person
163 # has_attached_file :avatar, :default_url => :default_url_by_gender
164 #
165 # private
166 #
167 # def default_url_by_gender
168 # "/assets/avatars/default_#{gender}.png"
169 # end
170 # end
03f777f8 »
2012-03-16 Extract some modules from Paperclip.rb
171 def has_attached_file(name, options = {})
d68a9421 »
2007-11-09 Re-refactoring
172 include InstanceMethods
f99b0fd5 »
2007-11-15 Validations work as expected with invalid images.
173
fd6eba32 »
2011-05-23 Fix problem occurred from undefined `inheritable_attributes` in Rails…
174 if attachment_definitions.nil?
5232b192 »
2012-03-06 Remove Rails 2 support from Paperclip
175 self.attachment_definitions = {}
2c6b7cb0 »
2011-09-25 Fix 293, 601: STI subclassing overwrites options
176 else
5232b192 »
2012-03-06 Remove Rails 2 support from Paperclip
177 self.attachment_definitions = self.attachment_definitions.dup
fd6eba32 »
2011-05-23 Fix problem occurred from undefined `inheritable_attributes` in Rails…
178 end
179
5f8140d1 »
2012-02-03 passing AttachmentOptions instance instead of hash to Attachment.new
180 attachment_definitions[name] = Paperclip::AttachmentOptions.new(options)
72430159 »
2011-09-30 We don't need to check if something is included in Set.
181 Paperclip.classes_with_attachments << self.name
8d43e19e »
2011-09-07 fixes #588 . Attempt to log warning message when 2 models use same at…
182 Paperclip.check_for_url_clash(name,attachment_definitions[name][:url],self.name)
d68a9421 »
2007-11-09 Re-refactoring
183
2784b380 »
2008-03-18 Huge refactoring.
184 after_save :save_attached_files
472a625a »
2011-08-26 Fixing destroy callback to delete files just when model destroy metho…
185 before_destroy :prepare_for_destroy
186 after_destroy :destroy_attached_files
d68a9421 »
2007-11-09 Re-refactoring
187
9cd1f8e1 »
2010-04-18 Use Rails 3 callbacks.
188 define_paperclip_callbacks :post_process, :"#{name}_post_process"
189
2784b380 »
2008-03-18 Huge refactoring.
190 define_method name do |*args|
191 a = attachment_for(name)
192 (args.length > 0) ? a.to_s(args.first) : a
193 end
d68a9421 »
2007-11-09 Re-refactoring
194
2784b380 »
2008-03-18 Huge refactoring.
195 define_method "#{name}=" do |file|
196 attachment_for(name).assign(file)
8911e40e »
2007-10-25 New hotness. Holy crap.
197 end
d68a9421 »
2007-11-09 Re-refactoring
198
2784b380 »
2008-03-18 Huge refactoring.
199 define_method "#{name}?" do
ffb0e01b »
2008-08-01 Shorten !attachment.original_filename.blank? to attachment.file?
200 attachment_for(name).file?
2784b380 »
2008-03-18 Huge refactoring.
201 end
f99b0fd5 »
2007-11-15 Validations work as expected with invalid images.
202
2784b380 »
2008-03-18 Huge refactoring.
203 validates_each(name) do |record, attr, value|
4a05a8a5 »
2009-02-01 Use attachment_for when validating attachments. Never know when someo…
204 attachment = record.attachment_for(name)
51637fe9 »
2009-12-31 Removed validation code left over from switching to more AR-ish valid…
205 attachment.send(:flush_errors)
2784b380 »
2008-03-18 Huge refactoring.
206 end
d68a9421 »
2007-11-09 Re-refactoring
207 end
208
e345764e »
2008-12-29 Updated documentation. Also changed the defaults of :path and :url to…
209 # Returns the attachment definitions defined by each call to
210 # has_attached_file.
8cdc876a »
2008-04-16 Changed the @attachment_definitions hash to be referenced through the…
211 def attachment_definitions
5232b192 »
2012-03-06 Remove Rails 2 support from Paperclip
212 self.attachment_definitions
8cdc876a »
2008-04-16 Changed the @attachment_definitions hash to be referenced through the…
213 end
d68a9421 »
2007-11-09 Re-refactoring
214 end
8911e40e »
2007-10-25 New hotness. Holy crap.
215 end
89c8d117 »
2011-12-02 Adds IO adapters to abstract the things that can be assigned.
216
217 # This stuff needs to be run after Paperclip is defined.
218 require 'paperclip/io_adapters/registry'
b920ee4d »
2012-06-08 Move some IOAdapters code to superclass, fix bug with tildes in filen…
219 require 'paperclip/io_adapters/abstract_adapter'
89c8d117 »
2011-12-02 Adds IO adapters to abstract the things that can be assigned.
220 require 'paperclip/io_adapters/identity_adapter'
221 require 'paperclip/io_adapters/file_adapter'
222 require 'paperclip/io_adapters/stringio_adapter'
223 require 'paperclip/io_adapters/nil_adapter'
224 require 'paperclip/io_adapters/attachment_adapter'
225 require 'paperclip/io_adapters/uploaded_file_adapter'
5d06ad8c »
2012-07-20 Allow for URI Adapter as an optional paperclip io adapter
226 require 'paperclip/io_adapters/uri_adapter'
Something went wrong with that request. Please try again.