module Mongoid::Document

This is the base module for all domain objects that need to be persisted to the database as documents.

Attributes

criteria_instance_id[RW]
new_record[R]

Public Class Methods

new(attrs = nil, options = nil) { |self| ... } click to toggle source

Instantiate a new Document, setting the Document's attributes if given. If no attributes are provided, they will be initialized with an empty Hash.

If a primary key is defined, the document's id will be set to that key, otherwise it will be set to a fresh Moped::BSON::ObjectId string.

@example Create a new document.

Person.new(:title => "Sir")

@param [ Hash ] attrs The attributes to set up the document with. @param [ Hash ] options A mass-assignment protection options. Supports

:as and :without_protection

@return [ Document ] A new document.

@since 1.0.0

# File lib/mongoid/document.rb, line 87
def initialize(attrs = nil, options = nil)
  _building do
    @new_record = true
    @attributes ||= {}
    options ||= {}
    apply_pre_processed_defaults
    process_attributes(attrs, options[:as] || :default, !options[:without_protection]) do
      yield(self) if block_given?
    end
    apply_post_processed_defaults
    # @todo: #2586: Need to have access to parent document in these
    #   callbacks.
    run_callbacks(:initialize) unless _initialize_callbacks.empty?
  end
end

Public Instance Methods

_destroy() click to toggle source

Used in conjunction with fields_for to build a form element for the destruction of this association. Always returns false because Mongoid only supports immediate deletion of associations.

See ActionView::Helpers::FormHelper::fields_for for more info.

# File lib/mongoid/railties/document.rb, line 8
def _destroy
  false
end
as_document() click to toggle source

Return a hash of the entire document hierarchy from this document and below. Used when the attributes are needed for everything and not just the current document.

@example Get the full hierarchy.

person.as_document

@return [ Hash ] A hash of all attributes in the hierarchy.

@since 1.0.0

# File lib/mongoid/document.rb, line 149
def as_document
  return attributes if frozen?
  embedded_relations.each_pair do |name, meta|
    without_autobuild do
      relation, stored = send(name), meta.store_as
      if attributes.has_key?(stored) || !relation.blank?
        if relation
          attributes[stored] = relation.as_document
        else
          attributes.delete(stored)
        end
      end
    end
  end
  attributes
end
becomes(klass) click to toggle source

Returns an instance of the specified class with the attributes, errors, and embedded documents of the current document.

@example Return a subclass document as a superclass instance.

manager.becomes(Person)

@raise [ ArgumentError ] If the class doesn't include Mongoid::Document

@param [ Class ] klass The class to become.

@return [ Document ] An instance of the specified class.

@since 2.0.0

# File lib/mongoid/document.rb, line 179
def becomes(klass)
  unless klass.include?(Mongoid::Document)
    raise ArgumentError, "A class which includes Mongoid::Document is expected"
  end

  became = klass.new(clone_document, without_protection: true)
  became.id = id
  became.instance_variable_set(:@changed_attributes, changed_attributes)
  became.instance_variable_set(:@errors, errors)
  became.instance_variable_set(:@new_record, new_record?)
  became.instance_variable_set(:@destroyed, destroyed?)
  became.changed_attributes["_type"] = self.class.to_s
  became._type = klass.to_s

  # mark embedded docs as persisted
  embedded_relations.each_pair do |name, meta|
    without_autobuild do
      relation = became.__send__(name)
      Array.wrap(relation).each do |r|
        r.instance_variable_set(:@new_record, new_record?)
      end
    end
  end

  IdentityMap.set(became) unless became.new_record?
  became
end
cache_key() click to toggle source

Print out the cache key. This will append different values on the plural model name.

If #new_record? - will append /new If not - will append /id-updated_at.to_s(:number) Without updated_at - will append /id

This is usually called insode a cache() block

@example Returns the cache key

document.cache_key

@return [ String ] the string with or without updated_at

@since 2.4.0

# File lib/mongoid/document.rb, line 222
def cache_key
  return "#{model_key}/new" if new_record?
  return "#{model_key}/#{id}-#{updated_at.utc.to_s(:number)}" if do_or_do_not(:updated_at)
  "#{model_key}/#{id}"
end
freeze() click to toggle source

Freezes the internal attributes of the document.

@example Freeze the document

document.freeze

@return [ Document ] The document.

@since 2.0.0

# File lib/mongoid/document.rb, line 24
def freeze
  as_document.freeze and self
end
frozen?() click to toggle source

Checks if the document is frozen

@example Check if frozen

document.frozen?

@return [ true, false ] True if frozen, else false.

@since 2.0.0

# File lib/mongoid/document.rb, line 36
def frozen?
  attributes.frozen?
end
hash() click to toggle source

Delegates to identity in order to allow two records of the same identity to work with something like:

[ Person.find(1), Person.find(2), Person.find(3) ] &
[ Person.find(1), Person.find(4) ] # => [ Person.find(1) ]

@example Get the hash.

document.hash

@return [ Integer ] The hash of the document's identity.

@since 1.0.0

# File lib/mongoid/document.rb, line 52
def hash
  identity.hash
end
identity() click to toggle source

A Document's is identified absolutely by its class and database id:

Person.first.identity #=> [Person, Moped::BSON::ObjectId('4f775130a04745933a000003')]

@example Get the identity

document.identity

@return [ Array ] An array containing [document.class, document.id]

@since 3.0.0

# File lib/mongoid/document.rb, line 66
def identity
  [ self.class, self.id ]
end
model_name() click to toggle source

Return the model name of the document.

@example Return the model name.

document.model_name

@return [ String ] The model name.

@since 3.0.16

# File lib/mongoid/document.rb, line 111
def model_name
  self.class.model_name
end
to_a() click to toggle source

Return an array with this Document only in it.

@example Return the document in an array.

document.to_a

@return [ Array<Document> ] An array with the document as its only item.

@since 1.0.0

# File lib/mongoid/document.rb, line 135
def to_a
  [ self ]
end
to_key() click to toggle source

Return the key value for the document.

@example Return the key.

document.to_key

@return [ Object ] The id of the document or nil if new.

@since 2.4.0

# File lib/mongoid/document.rb, line 123
def to_key
  (persisted? || destroyed?) ? [ id ] : nil
end

Private Instance Methods

logger() click to toggle source

Returns the logger

@return [ Logger ] The configured logger or a default Logger instance.

@since 2.2.0

# File lib/mongoid/document.rb, line 235
def logger
  Mongoid.logger
end
model_key() click to toggle source

Get the name of the model used in caching.

@example Get the model key.

model.model_key

@return [ String ] The model key.

@since 2.4.0

# File lib/mongoid/document.rb, line 247
def model_key
  @model_cache_key ||= "#{self.class.model_name.cache_key}"
end
to_ary() click to toggle source

Implement this for calls to flatten on array.

@example Get the document as an array.

document.to_ary

@return [ nil ] Always nil.

@since 2.1.0

# File lib/mongoid/document.rb, line 259
def to_ary
  nil
end