Class: Paperclip::Attachment

Inherits:
Object
  • Object
show all
Defined in:
lib/paperclip/attachment.rb

Overview

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.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, instance, options = {}) ⇒ Attachment

Creates an Attachment object. name is the name of the attachment, instance is the ActiveRecord object instance it's attached to, and options is the same as the hash passed to has_attached_file.



23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/paperclip/attachment.rb', line 23

def initialize name, instance, options = {}
  @name              = name
  @instance          = instance

  options = self.class.default_options.merge(options)

  @url               = options[:url]
  @path              = options[:path]
  @styles            = options[:styles]
  @default_url       = options[:default_url]
  @validations       = options[:validations]
  @default_style     = options[:default_style]
  @storage           = options[:storage]
  @whiny_thumbnails  = options[:whiny_thumbnails]
  @options           = options
  @queued_for_delete = []
  @queued_for_write  = {}
  @errors            = []
  @validation_errors = nil
  @dirty             = false

  normalize_style_definition
  initialize_storage
end

Instance Attribute Details

#default_style ⇒ Object (readonly)

Returns the value of attribute default_style.



18
19
20
 
# File 'lib/paperclip/attachment.rb', line 18

def default_style
  @default_style
end

#instance ⇒ Object (readonly)

Returns the value of attribute instance.



18
19
20
 
# File 'lib/paperclip/attachment.rb', line 18

def instance
  @instance
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



18
19
20
 
# File 'lib/paperclip/attachment.rb', line 18

def name
  @name
end

#styles ⇒ Object (readonly)

Returns the value of attribute styles.



18
19
20
 
# File 'lib/paperclip/attachment.rb', line 18

def styles
  @styles
end

Class Method Details

.default_options ⇒ Object 



6
7
8
9
10
11
12
13
14
15
16
 
# File 'lib/paperclip/attachment.rb', line 6

def self.default_options
  @default_options ||= {
    :url           => "/:attachment/:id/:style/:basename.:extension",
    :path          => ":rails_root/public/:attachment/:id/:style/:basename.:extension",
    :styles        => {},
    :default_url   => "/:attachment/:style/missing.png",
    :default_style => :original,
    :validations   => [],
    :storage       => :filesystem
  }
end

.interpolations ⇒ Object

A hash of procs that are run during the interpolation of a path or url. A variable of the format :name will be replaced with the return value of the proc named ":name". Each lambda takes the attachment and the current style as arguments. This hash can be added to with your own proc if necessary.



134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/paperclip/attachment.rb', line 134

def self.interpolations
  @interpolations ||= {
    :rails_root   => lambda{|attachment,style| RAILS_ROOT },
    :class        => lambda do |attachment,style|
                       attachment.instance.class.name.underscore.pluralize
                     end,
    :basename     => lambda do |attachment,style|
                       attachment.original_filename.gsub(File.extname(attachment.original_filename), "")
                     end,
    :extension    => lambda do |attachment,style| 
                       ((style = attachment.styles[style]) && style.last) ||
                       File.extname(attachment.original_filename).gsub(/^\.+/, "")
                     end,
    :id           => lambda{|attachment,style| attachment.instance.id },
    :id_partition => lambda do |attachment, style|
                       ("%09d" % attachment.instance.id).scan(/\d{3}/).join("/")
                     end,
    :attachment   => lambda{|attachment,style| attachment.name.to_s.downcase.pluralize },
    :style        => lambda{|attachment,style| style || attachment.default_style },
  }
end

Instance Method Details

#assign(uploaded_file) ⇒ Object

What gets called when you call instance.attachment = File. It clears errors, assigns attributes, processes the file, and runs validations. It also queues up the previous file for deletion, to be flushed away on #save of its host.



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/paperclip/attachment.rb', line 51

def assign uploaded_file
  return nil unless valid_assignment?(uploaded_file)

  queue_existing_for_delete
  @errors            = []
  @validation_errors = nil

  return nil if uploaded_file.nil?

  @queued_for_write[:original]        = uploaded_file.to_tempfile
  @instance[:"#{@name}_file_name"]    = uploaded_file.original_filename.strip.gsub /[^\w\d\.\-]+/, '_'
  @instance[:"#{@name}_content_type"] = uploaded_file.content_type.strip
  @instance[:"#{@name}_file_size"]    = uploaded_file.size.to_i

  @dirty = true

  post_process
ensure
  validate
end

#dirty? ⇒ Boolean

Returns true if there are changes that need to be saved.

Returns:

  • (Boolean) 


105
106
107
 
# File 'lib/paperclip/attachment.rb', line 105

def dirty?
  @dirty
end

#errors ⇒ Object

Returns an array containing the errors on this attachment.



100
101
102
 
# File 'lib/paperclip/attachment.rb', line 100

def errors
  @errors.compact.uniq
end

#original_filename ⇒ Object

Returns the name of the file as originally assigned, and as lives in the _file_name attribute of the model.



125
126
127
 
# File 'lib/paperclip/attachment.rb', line 125

def original_filename
  instance[:"#{name}_file_name"]
end

#path(style = nil) ⇒ Object

Returns the path of the attachment as defined by the :path optionn. 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 th URL, and the :bucket option refers to the S3 bucket.



85
86
87
 
# File 'lib/paperclip/attachment.rb', line 85

def path style = nil #:nodoc:
  interpolate(@path, style)
end

#reprocess! ⇒ Object

This method really shouldn't be called that often. It's expected use is in the paperclip:refresh rake task and that's it. It will regenerate all thumbnails forcefully, by reobtaining the original file and going through the post-process again.



160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/paperclip/attachment.rb', line 160

def reprocess!
  new_original = Tempfile.new("paperclip-reprocess")
  old_original = to_file(:original)
  new_original.write( old_original.read )
  new_original.rewind

  @queued_for_write = { :original => new_original }
  post_process

  old_original.close if old_original.respond_to?(:close)
end

#save ⇒ Object

Saves the file, if there are no errors. If there are, it flushes them to the instance's errors and returns false, cancelling the save.



111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/paperclip/attachment.rb', line 111

def save
  if valid?
    flush_deletes
    flush_writes
    @dirty = false
    true
  else
    flush_errors
    false
  end
end

#to_s(style = nil) ⇒ Object

Alias to url



90
91
92
 
# File 'lib/paperclip/attachment.rb', line 90

def to_s style = nil
  url(style)
end

#url(style = default_style) ⇒ Object

Returns the public URL of the attachment, with a given style. Note that this does not necessarily need to point to a file that your web server can access and can point to an action in your app, if you need fine grained security. This is not recommended if you don't need the security, however, for performance reasons.



77
78
79
 
# File 'lib/paperclip/attachment.rb', line 77

def url style = default_style
  original_filename.nil? ? interpolate(@default_url, style) : interpolate(@url, style)
end

#valid? ⇒ Boolean

Returns true if there are any errors on this attachment.

Returns:

  • (Boolean) 


95
96
97
 
# File 'lib/paperclip/attachment.rb', line 95

def valid?
  errors.length == 0
end