From 92536c08d53c5d54f6c526bfdc5d854dd00a7a88 Mon Sep 17 00:00:00 2001 From: David Heinemeier Hansson Date: Mon, 24 Jul 2017 15:36:30 -0500 Subject: Document the rest of lib --- lib/active_storage/attached/macros.rb | 18 ++++++++++++++++++ lib/active_storage/attached/many.rb | 16 ++++++++++------ lib/active_storage/attached/one.rb | 11 ++++++++--- 3 files changed, 36 insertions(+), 9 deletions(-) (limited to 'lib/active_storage/attached') diff --git a/lib/active_storage/attached/macros.rb b/lib/active_storage/attached/macros.rb index 11f88f16e5..89297e5bdf 100644 --- a/lib/active_storage/attached/macros.rb +++ b/lib/active_storage/attached/macros.rb @@ -9,6 +9,15 @@ module ActiveStorage::Attached::Macros # There is no column defined on the model side, Active Storage takes # care of the mapping between your records and the attachment. # + # Under the covers, this relationship is implemented as a `has_one` association to a + # `ActiveStorage::Attachment` record and a `has_one-through` association to a + # `ActiveStorage::Blob` record. These associations are available as `avatar_attachment` + # and `avatar_blob`. But you shouldn't need to work with these associations directly in + # most circumstances. + # + # The system has been designed to having you go through the `ActiveStorage::Attached::One` + # proxy that provides the dynamic proxy to the associations and factory methods, like `#attach`. + # # If the +:dependent+ option isn't set, the attachment will be purged # (i.e. destroyed) whenever the record is destroyed. def has_one_attached(name, dependent: :purge_later) @@ -38,6 +47,15 @@ module ActiveStorage::Attached::Macros # # Gallery.where(user: Current.user).with_attached_photos # + # Under the covers, this relationship is implemented as a `has_many` association to a + # `ActiveStorage::Attachment` record and a `has_many-through` association to a + # `ActiveStorage::Blob` record. These associations are available as `photos_attachments` + # and `photos_blobs`. But you shouldn't need to work with these associations directly in + # most circumstances. + # + # The system has been designed to having you go through the `ActiveStorage::Attached::Many` + # proxy that provides the dynamic proxy to the associations and factory methods, like `#attach`. + # # If the +:dependent+ option isn't set, all the attachments will be purged # (i.e. destroyed) whenever the record is destroyed. def has_many_attached(name, dependent: :purge_later) diff --git a/lib/active_storage/attached/many.rb b/lib/active_storage/attached/many.rb index ea4aade5d7..035cd9c091 100644 --- a/lib/active_storage/attached/many.rb +++ b/lib/active_storage/attached/many.rb @@ -1,24 +1,28 @@ -# Representation of multiple attachments to a model. +# Decorated proxy object representing of multiple attachments to a model. class ActiveStorage::Attached::Many < ActiveStorage::Attached delegate_missing_to :attachments # Returns all the associated attachment records. # - # You don't have to call this method to access the attachments' methods as - # they are all available at the model level. + # All methods called on this proxy object that aren't listed here will automatically be delegated to `attachments`. def attachments record.public_send("#{name}_attachments") end - # Associates one or several attachments with the current record, saving - # them to the database. + # Associates one or several attachments with the current record, saving them to the database. + # Examples: + # + # document.images.attach(params[:images]) # Array of ActionDispatch::Http::UploadedFile objects + # document.images.attach(params[:signed_blob_id]) # Signed reference to blob from direct upload + # document.images.attach(io: File.open("~/racecar.jpg"), filename: "racecar.jpg", content_type: "image/jpg") + # document.images.attach([ first_blob, second_blob ]) def attach(*attachables) attachables.flatten.collect do |attachable| attachments.create!(name: name, blob: create_blob_from(attachable)) end end - # Checks the presence of attachments. + # Returns true if any attachments has been made. # # class Gallery < ActiveRecord::Base # has_many_attached :photos diff --git a/lib/active_storage/attached/one.rb b/lib/active_storage/attached/one.rb index d255412842..0c522e856e 100644 --- a/lib/active_storage/attached/one.rb +++ b/lib/active_storage/attached/one.rb @@ -10,14 +10,19 @@ class ActiveStorage::Attached::One < ActiveStorage::Attached record.public_send("#{name}_attachment") end - # Associates a given attachment with the current record, saving it to the - # database. + # Associates a given attachment with the current record, saving it to the database. + # Examples: + # + # person.avatar.attach(params[:avatar]) # ActionDispatch::Http::UploadedFile object + # person.avatar.attach(params[:signed_blob_id]) # Signed reference to blob from direct upload + # person.avatar.attach(io: File.open("~/face.jpg"), filename: "face.jpg", content_type: "image/jpg") + # person.avatar.attach(avatar_blob) # ActiveStorage::Blob object def attach(attachable) write_attachment \ ActiveStorage::Attachment.create!(record: record, name: name, blob: create_blob_from(attachable)) end - # Checks the presence of the attachment. + # Returns true if an attachment has been made. # # class User < ActiveRecord::Base # has_one_attached :avatar -- cgit v1.2.3