module Shrine::Plugins::Base::AttacherMethods

  1. lib/shrine.rb

Public Instance Aliases

attached? -> changed?

Attributes

cache [R]

Returns the uploader that is used for the temporary storage.

context [R]

Returns the context that will be sent to the uploader when uploading and deleting. Can be modified with additional data to be sent to the uploader.

errors [R]

Returns an array of validation errors created on file assignment in the Attacher.validate block.

store [R]

Returns the uploader that is used for the permanent storage.

Public Class methods

new (record, name, cache: :cache, store: :store)

Initializes the necessary attributes.

[show source]
# File lib/shrine.rb, line 517
def initialize(record, name, cache: :cache, store: :store)
  @cache   = shrine_class.new(cache)
  @store   = shrine_class.new(store)
  @context = {record: record, name: name}
  @errors  = []
end

Public Instance methods

_delete (uploaded_file, **options)

Delegates to delete!, overriden for backgrounding.

[show source]
# File lib/shrine.rb, line 614
def _delete(uploaded_file, **options)
  delete!(uploaded_file, **options)
end
_promote (uploaded_file = get, **options)

Delegates to promote, overriden for backgrounding.

[show source]
# File lib/shrine.rb, line 581
def _promote(uploaded_file = get, **options)
  promote(uploaded_file, **options)
end
assign (value, **options)

Receives the attachment value from the form. It can receive an already cached file as a JSON string, otherwise it assumes that it's an IO object and uploads it to the temporary storage. The cached file is then written to the attachment attribute in the JSON format.

[show source]
# File lib/shrine.rb, line 534
def assign(value, **options)
  if value.is_a?(String)
    return if value == "" || !cache.uploaded?(uploaded_file(value))
    assign_cached(uploaded_file(value))
  else
    uploaded_file = cache!(value, action: :cache, **options) if value
    set(uploaded_file)
  end
end
cache! (io, **options)

Uploads the file using the cache uploader, passing the context.

[show source]
# File lib/shrine.rb, line 650
def cache!(io, **options)
  Shrine.deprecation("Sending :phase to Attacher#cache! is deprecated and will not be supported in Shrine 3. Use :action instead.") if options[:phase]
  cache.upload(io, context.merge(_equalize_phase_and_action(options)))
end
cached? ()

Returns true if attachment is present and cached.

[show source]
# File lib/shrine.rb, line 625
def cached?
  file = get
  file && cache.uploaded?(file)
end
changed? ()

Returns true if a new file has been attached.

[show source]
# File lib/shrine.rb, line 561
def changed?
  instance_variable_defined?(:@old)
end
data_attribute ()

The name of the attribute on the model instance that is used to store the attachment data. Defaults to <attachment>_data.

[show source]
# File lib/shrine.rb, line 675
def data_attribute
  :"#{name}_data"
end
delete! (uploaded_file, **options)

Deletes the file using the uploader, passing the context.

[show source]
# File lib/shrine.rb, line 662
def delete!(uploaded_file, **options)
  Shrine.deprecation("Sending :phase to Attacher#delete! is deprecated and will not be supported in Shrine 3. Use :action instead.") if options[:phase]
  store.delete(uploaded_file, context.merge(_equalize_phase_and_action(options)))
end
destroy ()

Deletes the current attachment, typically called after destroying the record.

[show source]
# File lib/shrine.rb, line 608
def destroy
  file = get
  _delete(file, action: :destroy) if file && !cache.uploaded?(file)
end
finalize ()

Deletes the old file and promotes the new one. Typically this should be called after saving the model instance.

[show source]
# File lib/shrine.rb, line 573
def finalize
  return if !instance_variable_defined?(:@old)
  replace
  remove_instance_variable(:@old)
  _promote(action: :store) if cached?
end
get ()

Returns a Shrine::UploadedFile instantiated from the data written to the attachment attribute.

[show source]
# File lib/shrine.rb, line 638
def get
  uploaded_file(read) if read
end
name ()

Returns the attachment name associated with the attacher.

[show source]
# File lib/shrine.rb, line 528
def name;   context[:name];   end
promote (uploaded_file = get, **options)

Uploads the cached file to store, and writes the stored file to the attachment attribute.

[show source]
# File lib/shrine.rb, line 587
def promote(uploaded_file = get, **options)
  stored_file = store!(uploaded_file, **options)
  result = swap(stored_file) or _delete(stored_file, action: :abort)
  result
end
read ()

Reads from the <attachment>_data attribute on the model instance. It returns nil if the value is blank.

[show source]
# File lib/shrine.rb, line 644
def read
  value = record.send(data_attribute)
  convert_after_read(value) unless value.nil? || value.empty?
end
record ()

Returns the model instance associated with the attacher.

[show source]
# File lib/shrine.rb, line 525
def record; context[:record]; end
replace ()

Deletes the previous attachment that was replaced, typically called after the model instance is saved with the new attachment.

[show source]
# File lib/shrine.rb, line 602
def replace
  _delete(@old, action: :replace) if @old && !cache.uploaded?(@old)
end
save ()

Plugins can override this if they want something to be done before save.

[show source]
# File lib/shrine.rb, line 568
def save
end
set (uploaded_file)

Accepts a Shrine::UploadedFile object and writes it to the attachment attribute. It then runs file validations, and records that the attachment has changed.

[show source]
# File lib/shrine.rb, line 547
def set(uploaded_file)
  file = get
  @old = file unless uploaded_file == file
  _set(uploaded_file)
  validate
end
shrine_class ()

Returns the Shrine class that this attacher's class is namespaced under.

[show source]
# File lib/shrine.rb, line 681
def shrine_class
  self.class.shrine_class
end
store! (io, **options)

Uploads the file using the store uploader, passing the context.

[show source]
# File lib/shrine.rb, line 656
def store!(io, **options)
  Shrine.deprecation("Sending :phase to Attacher#store! is deprecated and will not be supported in Shrine 3. Use :action instead.") if options[:phase]
  store.upload(io, context.merge(_equalize_phase_and_action(options)))
end
stored? ()

Returns true if attachment is present and stored.

[show source]
# File lib/shrine.rb, line 631
def stored?
  file = get
  file && store.uploaded?(file)
end
swap (uploaded_file)

Calls update, overriden in ORM plugins, and returns true if the attachment was successfully updated.

[show source]
# File lib/shrine.rb, line 595
def swap(uploaded_file)
  update(uploaded_file)
  uploaded_file if uploaded_file == get
end
uploaded_file (object, &block)

Enhances Shrine.uploaded_file with the ability to recognize uploaded files as JSON strings.

[show source]
# File lib/shrine.rb, line 669
def uploaded_file(object, &block)
  shrine_class.uploaded_file(object, &block)
end
url (**options)

Returns the URL to the attached file if it's present. It forwards any given URL options to the storage.

[show source]
# File lib/shrine.rb, line 620
def url(**options)
  get.url(**options) if read
end
validate ()

Runs the validations defined by Attacher.validate.

[show source]
# File lib/shrine.rb, line 555
def validate
  errors.clear
  validate_block if get
end