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 11 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, :adapter_options => { hash_digest: Digest::MD5 }, :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 (which is
a special case that indicates all styles should be processed)
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 72 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) @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 99 def assign(uploaded_file) @file = Paperclip.io_adapters.for(uploaded_file, @options[:adapter_options]) 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 151 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 161 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 169 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 143 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