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 498
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 593
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 561
def _promote(uploaded_file = get, **options)
  promote(uploaded_file, **options)
end
assign (value)

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 515
def assign(value)
  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) 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 627
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 604
def cached?
  get && cache.uploaded?(get)
end
changed? ()

Returns true if a new file has been attached.

[show source]
# File lib/shrine.rb, line 541
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 652
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 639
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 588
def destroy
  _delete(get, action: :destroy) if get && !cache.uploaded?(get)
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 553
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 615
def get
  uploaded_file(read) if read
end
name ()

Returns the attachment name associated with the attacher.

[show source]
# File lib/shrine.rb, line 509
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 567
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 621
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 506
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 582
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 548
def save
end
set (uploaded_file)

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

[show source]
# File lib/shrine.rb, line 528
def set(uploaded_file)
  @old = get unless uploaded_file == get
  _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 658
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 633
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 609
def stored?
  get && store.uploaded?(get)
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 575
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 646
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 599
def url(**options)
  get.url(**options) if read
end
validate ()

Runs the validations defined by Attacher.validate.

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