Class: Mongoid::Association::Many

Inherits:
Association::Proxy
  • Object
show all
Extended by:
Forwardable
Includes:
Enumerable
Defined in:
lib/mongoid/association/many.rb

Overview

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

Instance Method Summary collapse

Instance Method Details

#blank? ⇒ true | false

Is the association empty?

Examples:

Is the association empty??

person.addresses.blank?

Returns:

  • (true | false) —

    If the association is empty or not.



28
29
30
 
# File 'lib/mongoid/association/many.rb', line 28

def blank?
  !any?
end

#cache_version(timestamp_column = :updated_at) ⇒ String

For compatibility with Rails' caching. Returns a string based on the given timestamp, and includes the number of records in the relation in the version.

Parameters:

  • timestamp_column (String | Symbol) (defaults to: :updated_at) —

    the timestamp column to use when constructing the key.

Returns:

  • (String) —

    the cache version string



195
196
197
198
 
# File 'lib/mongoid/association/many.rb', line 195

def cache_version(timestamp_column = :updated_at)
  @cache_version ||= {}
  @cache_version[timestamp_column] ||= compute_cache_version(timestamp_column)
end

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

Creates a new document on the references many association. 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.



42
43
44
45
46
47
48
49
50
 
# File 'lib/mongoid/association/many.rb', line 42

def create(attributes = nil, type = nil, &block)
  if attributes.is_a?(::Array)
    attributes.map { |attrs| create(attrs, type, &block) }
  else
    doc = build(attributes, type, &block)
    _base.persisted? ? doc.save : raise_unsaved(doc)
    doc
  end
end

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

Creates a new document on the references many association. 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:



65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/mongoid/association/many.rb', line 65

def create!(attributes = nil, type = nil, &block)
  if attributes.is_a?(::Array)
    attributes.map { |attrs| create!(attrs, type, &block) }
  else
    doc = build(attributes, type, &block)

    Array(doc).each do |doc|
      doc.try(:run_pending_callbacks)
    end

    _base.persisted? ? doc.save! : raise_unsaved(doc)
    doc
  end
end

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

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

@param [ Hash ] attrs The attributes to search or create with. @param [ Class ] type The optional type of document to create.

Examples:

Find or create.

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

Returns:

  • (Document) —

    An existing document or newly created one.



90
91
92
 
# File 'lib/mongoid/association/many.rb', line 90

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

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

Find the first document given the conditions, or creates a new document with the conditions that were supplied. This will raise an error if validation fails.

Examples:

Find or create.

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

Parameters:

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

    The attributes to search or create with.

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

    The optional type of document to create.

Returns:

  • (Document) —

    An existing document or newly created one.

Raises:



106
107
108
 
# File 'lib/mongoid/association/many.rb', line 106

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

#find_or_initialize_by(attrs = {}, type = nil, &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.

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

    The optional subclass to build.

Returns:

  • (Document) —

    An existing document or newly instantiated one.



120
121
122
 
# File 'lib/mongoid/association/many.rb', line 120

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

#nil? ⇒ false

This proxy can never be nil.

Examples:

Is the proxy nil?

relation.nil?

Returns:

  • (false) —

    Always false.



130
131
132
 
# File 'lib/mongoid/association/many.rb', line 130

def nil?
  false
end

#respond_to?(name, include_private = false) ⇒ 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.

  • include_private (true | false) (defaults to: false) —

    Whether to include private methods.

Returns:

  • (true | false) —

    If the proxy responds to the method.



143
144
145
146
 
# File 'lib/mongoid/association/many.rb', line 143

def respond_to?(name, include_private = false)
  [].respond_to?(name, include_private) ||
    klass.respond_to?(name, include_private) || super
end

#scoped ⇒ Criteria

This is public access to the association's criteria.

Examples:

Get the scoped association.

relation.scoped

Returns:



154
155
156
 
# File 'lib/mongoid/association/many.rb', line 154

def scoped
  criteria
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):

  • :except (Symbol | String | Array<Symbol | String>) —

    Do not include these field(s).

  • :include (Symbol | String | Array<Symbol | String>) —

    Which association(s) to include.

  • :only (Symbol | String | Array<Symbol | String>) —

    Limit the field(s) to only these.

Returns:

  • (Hash) —

    The documents, ready to be serialized.



172
173
174
 
# File 'lib/mongoid/association/many.rb', line 172

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

#unscoped ⇒ Criteria

Get a criteria for the embedded documents without the default scoping applied.

Examples:

Get the unscoped criteria.

person.addresses.unscoped

Returns:



183
184
185
 
# File 'lib/mongoid/association/many.rb', line 183

def unscoped
  criteria.unscoped
end