This class defines the behaviour for all relations that are a one-to-many between documents in different collections.
Appends a document or array of documents to the relation. Will set the parent and update the index in the process.
@example Append a document.
person.posts << post
@example Push a document.
person.posts.push(post)
@example Concat with other documents.
person.posts.concat([ post_one, post_two ])
@param [ Document, Array<Document> ] *args Any number of documents.
@return [ Array<Document> ] The loaded docs.
@since 2.0.0.beta.1
# File lib/mongoid/relations/referenced/many.rb, line 30 def <<(*args) batched do args.flatten.each do |doc| next unless doc append(doc) doc.save if persistable? && !doc.validated? end end end
Build a new document from the attributes and append it to this relation without saving.
@example Build a new document on the relation.
person.posts.build(:title => "A new post")
@overload build(attributes = {}, options = {}, type = nil)
@param [ Hash ] attributes The attributes of the new document. @param [ Hash ] options The scoped assignment options. @param [ Class ] type The optional subclass to build.
@overload build(attributes = {}, type = nil)
@param [ Hash ] attributes The attributes of the new document. @param [ Class ] type The optional subclass to build.
@return [ Document ] The new document.
@since 2.0.0.beta.1
# File lib/mongoid/relations/referenced/many.rb, line 60 def build(attributes = {}, options = {}, type = nil) if options.is_a? Class options, type = {}, options end Factory.build(type || klass, attributes, options).tap do |doc| append(doc) yield(doc) if block_given? end end
Creates a new document on the references many relation. This will save the document if the parent has been persisted.
@example Create and save the new document.
person.posts.create(:text => "Testing")
@overload create(attributes = nil, options = {}, type = nil)
@param [ Hash ] attributes The attributes to create with. @param [ Hash ] options The scoped assignment options. @param [ Class ] type The optional type of document to create.
@overload create(attributes = nil, type = nil)
@param [ Hash ] attributes The attributes to create with. @param [ Class ] type The optional type of document to create.
@return [ Document ] The newly created document.
@since 2.0.0.beta.1
# File lib/mongoid/relations/referenced/many.rb, line 90 def create(attributes = nil, options = {}, type = nil, &block) build(attributes, options, type, &block).tap do |doc| base.persisted? ? doc.save : raise_unsaved(doc) end end
Creates a new document on the references many relation. This will save the document if the parent has been persisted and will raise an error if validation fails.
@example Create and save the new document.
person.posts.create!(:text => "Testing")
@overload create!(attributes = nil, options = {}, type = nil)
@param [ Hash ] attributes The attributes to create with. @param [ Hash ] options The scoped assignment options. @param [ Class ] type The optional type of document to create.
@overload create!(attributes = nil, type = nil)
@param [ Hash ] attributes The attributes to create with. @param [ Class ] type The optional type of document to create.
@raise [ Errors::Validations ] If validation failed.
@return [ Document ] The newly created document.
@since 2.0.0.beta.1
# File lib/mongoid/relations/referenced/many.rb, line 117 def create!(attributes = nil, options = {}, type = nil, &block) build(attributes, options, type, &block).tap do |doc| base.persisted? ? doc.save! : raise_unsaved(doc) end end
Delete the document from the relation. This will set the foreign key on the document to nil. If the dependent options on the relation are :delete or :destroy the appropriate removal will occur.
@example Delete the document.
person.posts.delete(post)
@param [ Document ] document The document to remove.
@return [ Document ] The matching document.
@since 2.1.0
# File lib/mongoid/relations/referenced/many.rb, line 135 def delete(document) target.delete(document) do |doc| if doc unbind_one(doc) cascade!(doc) end end end
Deletes all related documents from the database given the supplied conditions.
@example Delete all documents in the relation.
person.posts.delete_all
@example Conditonally delete all documents in the relation.
person.posts.delete_all(:conditions => { :title => "Testing" })
@param [ Hash ] conditions Optional conditions to delete with.
@return [ Integer ] The number of documents deleted.
@since 2.0.0.beta.1
# File lib/mongoid/relations/referenced/many.rb, line 158 def delete_all(conditions = nil) remove_all(conditions, :delete_all) end
Destroys all related documents from the database given the supplied conditions.
@example Destroy all documents in the relation.
person.posts.destroy_all
@example Conditonally destroy all documents in the relation.
person.posts.destroy_all(:conditions => { :title => "Testing" })
@param [ Hash ] conditions Optional conditions to destroy with.
@return [ Integer ] The number of documents destroyd.
@since 2.0.0.beta.1
# File lib/mongoid/relations/referenced/many.rb, line 176 def destroy_all(conditions = nil) remove_all(conditions, :destroy_all) end
Iterate over each document in the relation and yield to the provided block.
@note This will load the entire relation into memory.
@example Iterate over the documents.
person.posts.each do |post| post.save end
@return [ Array<Document> ] The loaded docs.
@since 2.1.0
# File lib/mongoid/relations/referenced/many.rb, line 193 def each target.each { |doc| yield(doc) if block_given? } end
Find the matchind document on the association, either based on id or conditions.
@example Find by an id.
person.posts.find(BSON::ObjectId.new)
@example Find by multiple ids.
person.posts.find([ BSON::ObjectId.new, BSON::ObjectId.new ])
@example Conditionally find all matching documents.
person.posts.find(:all, :conditions => { :title => "Sir" })
@example Conditionally find the first document.
person.posts.find(:first, :conditions => { :title => "Sir" })
@example Conditionally find the last document.
person.posts.find(:last, :conditions => { :title => "Sir" })
@param [ Symbol, BSON::ObjectId, Array<BSON::ObjectId> ] arg The
argument to search with.
@param [ Hash ] options The options to search with.
@return [ Document, Criteria ] The matching document(s).
@since 2.0.0.beta.1
# File lib/mongoid/relations/referenced/many.rb, line 222 def find(*args) criteria.find(*args) end
Removes all associations between the base document and the target documents by deleting the foreign keys and the references, orphaning the target documents in the process.
@example Nullify the relation.
person.posts.nullify
@since 2.0.0.rc.1
# File lib/mongoid/relations/referenced/many.rb, line 251 def nullify criteria.update(metadata.foreign_key => nil) target.clear do |doc| unbind_one(doc) end end
Clear the relation. Will delete the documents from the db if they are already persisted.
@example Clear the relation.
person.posts.clear
@return [ Many ] The relation emptied.
@since 2.0.0.beta.1
# File lib/mongoid/relations/referenced/many.rb, line 268 def purge unless metadata.destructive? nullify else criteria.delete_all target.clear do |doc| unbind_one(doc) doc.destroyed = true end end end
Substitutes the supplied target documents for the existing documents in the relation. If the new target is nil, perform the necessary deletion.
@example Replace the relation.
person.posts.substitute([ new_post ])
@param [ Array<Document> ] replacement The replacement target.
@return [ Many ] The relation.
@since 2.0.0.rc.1
# File lib/mongoid/relations/referenced/many.rb, line 293 def substitute(replacement) tap do |proxy| if replacement != proxy.in_memory proxy.purge proxy.push(replacement.compact.uniq) if replacement end end end
Instantiate a new references_many relation. Will set the foreign key and the base on the inverse object.
@example Create the new relation.
Referenced::Many.new(base, target, metadata)
@param [ Document ] base The document this relation hangs off of. @param [ Array<Document> ] target The target of the relation. @param [ Metadata ] metadata The relation’s metadata.
@since 2.0.0.beta.1
# File lib/mongoid/relations/referenced/many.rb, line 237 def initialize(base, target, metadata) init(base, Targets::Enumerable.new(target), metadata) do raise_mixed if klass.embedded? end end
Generated with the Darkfish Rdoc Generator 2.