Class/Module Index [+]

Quicksearch

Mongoid::Relations::Referenced::Many

This class defines the behaviour for all relations that are a one-to-many between documents in different collections.

Public Instance Methods

<<(*args) click to toggle source

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
Also aliased as: concat, push
build(attributes = {}, options = {}, type = nil) click to toggle source

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
Also aliased as: new
clear() click to toggle source
Alias for: purge
concat(*args) click to toggle source
Alias for: <<
create(attributes = nil, options = {}, type = nil, &block) click to toggle source

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
create!(attributes = nil, options = {}, type = nil, &block) click to toggle source

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(document) click to toggle source

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
delete_all(conditions = nil) click to toggle source

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
destroy_all(conditions = nil) click to toggle source

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
each() click to toggle source

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(*args) click to toggle source

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
new(attributes = {}, options = {}, type = nil) click to toggle source
Alias for: build
nullify() click to toggle source

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
Also aliased as: nullify_all
nullify_all() click to toggle source
Alias for: nullify
purge() click to toggle source

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
Also aliased as: clear
push(*args) click to toggle source
Alias for: <<
substitute(replacement) click to toggle source

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

Public Class Methods

new(base, target, metadata) click to toggle source

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

[Validate]

Generated with the Darkfish Rdoc Generator 2.