class Paperclip::Attachment
The Attachment class manages the files for a given attachment. It saves when the model saves, deletes when the model is destroyed, and processes the file upon assignment.
Attributes
Public Class Methods
# File lib/paperclip/attachment.rb, line 10 def self.default_options @default_options ||= { :convert_options => {}, :default_style => :original, :default_url => "/:attachment/:style/missing.png", :escape_url => true, :restricted_characters => /[&$+,\/:;=?@<>\[\]\{\}\|\\^~%# ]/, :filename_cleaner => nil, :hash_data => ":class/:attachment/:id/:style/:updated_at", :hash_digest => "SHA1", :interpolator => Paperclip::Interpolations, :only_process => [], :path => ":rails_root/public:url", :preserve_files => false, :processors => [:thumbnail], :source_file_options => {}, :storage => :filesystem, :styles => {}, :url => "/system/:class/:attachment/:id_partition/:style/:filename", :url_generator => Paperclip::UrlGenerator, :use_default_time_zone => true, :use_timestamp => true, :whiny => Paperclip.options[:whiny] || Paperclip.options[:whiny_thumbnails], :validate_media_type => true, :check_validity_before_processing => true } end
Creates an Attachment object.
name
is the name of the attachment, instance
is
the model object instance it's attached to, and options
is
the same as the hash passed to has_attached_file
.
Options include:
url
- a relative URL of the attachment. This is interpolated
using interpolator
path
- where on the filesystem
to store the attachment. This is interpolated using
interpolator
styles
- a hash of options for
processing the attachment. See has_attached_file
for the
details only_process
- style args to be run through the
post-processor. This defaults to the empty list default_url
-
a URL for the missing image default_style
- the style to use
when an argument is not specified e.g. url, path storage
- the
storage mechanism. Defaults to :filesystem use_timestamp
-
whether to append an anti-caching timestamp to image URLs. Defaults to true
whiny
, whiny_thumbnails
- whether to raise when
thumbnailing fails use_default_time_zone
- related to
use_timestamp
. Defaults to true hash_digest
- a
string representing a class that will be used to hash URLs for obfuscation
hash_data
- the relative URL for the hash data. This is
interpolated using interpolator
hash_secret
- a
secret passed to the hash_digest
convert_options
- flags passed to the convert
command for processing
source_file_options
- flags passed to the convert
command that controls how the file is read processors
-
classes that transform the attachment. Defaults to [:thumbnail]
preserve_files
- whether to keep files on the filesystem when
deleting or clearing the attachment. Defaults to false
filename_cleaner
- An object that responds to call(filename)
that will strip unacceptable charcters from filename
interpolator
- the object used to interpolate filenames and
URLs. Defaults to Paperclip::Interpolations
url_generator
- the object used to generate URLs, using the
interpolator. Defaults to Paperclip::UrlGenerator
escape_url
- Perform URI escaping to URLs. Defaults to true
# File lib/paperclip/attachment.rb, line 69 def initialize(name, instance, options = {}) @name = name.to_sym @name_string = name.to_s @instance = instance options = self.class.default_options.deep_merge(options) @options = options @post_processing = true @queued_for_delete = [] @queued_for_write = {} @errors = {} @dirty = false @interpolator = options[:interpolator] @url_generator = options[:url_generator].new(self, @options) @source_file_options = options[:source_file_options] @whiny = options[:whiny] initialize_storage end
Public Instance Methods
What gets called when you call instance.attachment = File. It clears errors, assigns attributes, and processes the file. It also queues up the previous file for deletion, to be flushed away on save of its host. In addition to form uploads, you can also assign another Paperclip attachment:
new_user.avatar = old_user.avatar
# File lib/paperclip/attachment.rb, line 96 def assign(uploaded_file) @file = Paperclip.io_adapters.for(uploaded_file) ensure_required_accessors! ensure_required_validations! if @file.assignment? clear(*only_process) if @file.nil? nil else assign_attributes post_process_file reset_file_if_original_reprocessed end else nil end end
# File lib/paperclip/attachment.rb, line 147 def default_options { :timestamp => @options[:use_timestamp], :escape => @options[:escape_url] } end
Alias to url
that allows using the #expiring_url method
provided by the cloud storage implementations, but keep using filesystem
storage for development and testing.
# File lib/paperclip/attachment.rb, line 157 def expiring_url(time = 3600, style_name = default_style) url(style_name) end
Returns the path of the attachment as defined by the :path option. If the file is stored in the filesystem the path refers to the path of the file on disk. If the file is stored in S3, the path is the “key” part of the URL, and the :bucket option refers to the S3 bucket.
# File lib/paperclip/attachment.rb, line 165 def path(style_name = default_style) path = original_filename.nil? ? nil : interpolate(path_option, style_name) path.respond_to?(:unescape) ? path.unescape : path end
Returns the public URL of the attachment with a given style. This does not necessarily need to point to a file that your Web server can access and can instead point to an action in your app, for example for fine grained security; this has a serious performance tradeoff.
Options:
timestamp
- Add a timestamp to the end of the URL. Default:
true. escape
- Perform URI escaping to the URL. Default:
true.
Global controls (set on has_attached_file):
interpolator
- The object that fills in a URL pattern's
variables. default_url
- The image to show when the
attachment has no image. url
- The URL for a saved
image. url_generator
- The object that generates a URL.
Default: Paperclip::UrlGenerator.
As mentioned just above, the object that generates this URL can be passed in, for finer control. This object must respond to two methods:
+#new(Paperclip::Attachment, options_hash)+ +#for(style_name, options_hash)+
# File lib/paperclip/attachment.rb, line 139 def url(style_name = default_style, options = {}) if options == true || options == false # Backwards compatibility. @url_generator.for(style_name, default_options.merge(:timestamp => options)) else @url_generator.for(style_name, default_options.merge(options)) end end