Class: Mongoid::Relations::Many

Inherits:
Proxy show all
Defined in:
lib/mongoid/relations/many.rb

Overview

This is the superclass for all many to one and many to many relation proxies.

Direct Known Subclasses

Embedded::Many, Referenced::Many

Instance Attribute Summary

Attributes inherited from Proxy

#base, #loaded, #metadata, #target

Instance Method Summary collapse

Methods inherited from Proxy

#init

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Mongoid::Relations::Proxy

Instance Method Details

#<<(*args) ⇒ Object Also known as: concat, push

Appends a document or array of documents to the relation. Will set the parent and update the index in the process.

Examples:

Append a document.

person.addresses << address

Push a document.

person.addresses.push(address)

Concat with other documents.

person.addresses.concat([ address_one, address_two ])

Parameters:



24
25
26
27
28
29
30
31
 
# File 'lib/mongoid/relations/many.rb', line 24

def <<(*args)
  options = default_options(args)
  args.flatten.each do |doc|
    return doc unless doc
    append(doc, options)
    doc.save if base.persisted? && !options[:binding]
  end
end

#build(attributes = {}, type = nil, &block) ⇒ Document Also known as: new

Builds a new document in the relation and appends it to the target. Takes an optional type if you want to specify a subclass.

Examples:

Build a new document on the relation.

person.people.build(:name => "Bozo")

Parameters:

  • attributes (Hash) (defaults to: {}) —

    The attributes to build the document with.

  • type (Class) (defaults to: nil) —

    Optional class to build the document with.

Returns:



45
46
47
48
49
50
51
52
 
# File 'lib/mongoid/relations/many.rb', line 45

def build(attributes = {}, type = nil, &block)
  instantiated(type).tap do |doc|
    doc.write_attributes(attributes)
    doc.identify
    append(doc, default_options(:binding => true))
    block.call(doc) if block
  end
end

#create(attributes = nil, type = nil, &block) ⇒ Document

Creates a new document on the references many relation. This will save the document if the parent has been persisted.

Examples:

Create and save the new document.

person.posts.create(:text => "Testing")

Parameters:

  • attributes (Hash) (defaults to: nil) —

    The attributes to create with.

  • type (Class) (defaults to: nil) —

    The optional type of document to create.

Returns:

  • (Document) —

    The newly created document.



65
66
67
68
69
70
 
# File 'lib/mongoid/relations/many.rb', line 65

def create(attributes = nil, type = nil, &block)
  build(attributes, type).tap do |doc|
    block.call(doc) if block
    doc.save if base.persisted?
  end
end

#create!(attributes = nil, type = nil) ⇒ Document

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.

Examples:

Create and save the new document.

person.posts.create!(:text => "Testing")

Parameters:

  • attributes (Hash) (defaults to: nil) —

    The attributes to create with.

  • type (Class) (defaults to: nil) —

    The optional type of document to create.

Returns:

  • (Document) —

    The newly created document.

Raises:



85
86
87
88
89
 
# File 'lib/mongoid/relations/many.rb', line 85

def create!(attributes = nil, type = nil)
  build(attributes, type).tap do |doc|
    doc.save! if base.persisted?
  end
end

#exists? ⇒ true, false

Determine if any documents in this relation exist in the database.

Examples:

Are there persisted documents?

person.posts.exists?

Returns:

  • (true, false) —

    True is persisted documents exist, false if not.



97
98
99
 
# File 'lib/mongoid/relations/many.rb', line 97

def exists?
  count > 0
end

#find_or_create_by(attrs = {}, &block) ⇒ Document

Find the first document given the conditions, or creates a new document with the conditions that were supplied.

Examples:

Find or create.

person.posts.find_or_create_by(:title => "Testing")

Parameters:

  • attrs (Hash) (defaults to: {}) —

    The attributes to search or create with.

Returns:

  • (Document) —

    An existing document or newly created one.



110
111
112
 
# File 'lib/mongoid/relations/many.rb', line 110

def find_or_create_by(attrs = {}, &block)
  find_or(:create, attrs, &block)
end

#find_or_initialize_by(attrs = {}, &block) ⇒ Document

Find the first Document given the conditions, or instantiates a new document with the conditions that were supplied

Examples:

Find or initialize.

person.posts.find_or_initialize_by(:title => "Test")

Parameters:

  • attrs (Hash) (defaults to: {}) —

    The attributes to search or initialize with.

Returns:

  • (Document) —

    An existing document or newly instantiated one.



123
124
125
 
# File 'lib/mongoid/relations/many.rb', line 123

def find_or_initialize_by(attrs = {}, &block)
  find_or(:build, attrs, &block)
end

#nil? ⇒ false

This proxy can never be nil.

Examples:

Is the proxy nil?

relation.nil?

Returns:

  • (false) —

    Always false.

Since:

  • 2.0.0



135
136
137
 
# File 'lib/mongoid/relations/many.rb', line 135

def nil?
  false
end

#respond_to?(name) ⇒ true, false

Since method_missing is overridden we should override this as well.

Examples:

Does the proxy respond to the method?

relation.respond_to?(:name)

Parameters:

  • name (Symbol) —

    The method name.

Returns:

  • (true, false) —

    If the proxy responds to the method.

Since:

  • 2.0.0



149
150
151
 
# File 'lib/mongoid/relations/many.rb', line 149

def respond_to?(name)
  [].respond_to?(name) || methods.include?(name)
end

#serializable_hash(options = {}) ⇒ Hash

Gets the document as a serializable hash, used by ActiveModel’s JSON and XML serializers. This override is just to be able to pass the :include and :except options to get associations in the hash.

Examples:

Get the serializable hash.

relation.serializable_hash

Parameters:

  • options (Hash) (defaults to: {}) —

    The options to pass.

Options Hash (options):

  • :include (Symbol) —

    What relations to include

  • :only (Symbol) —

    Limit the fields to only these.

  • :except (Symbol) —

    Dont include these fields.

Returns:

  • (Hash) —

    The documents, ready to be serialized.

Since:

  • 2.0.0.rc.6



169
170
171
 
# File 'lib/mongoid/relations/many.rb', line 169

def serializable_hash(options = {})
  target.map { |document| document.serializable_hash(options) }
end

#size ⇒ Integer Also known as: length

Always returns the number of documents that are in memory.

Examples:

Get the number of loaded documents.

relation.size

Returns:

  • (Integer) —

    The number of documents in memory.

Since:

  • 2.0.0



181
182
183
 
# File 'lib/mongoid/relations/many.rb', line 181

def size
  target.size
end