Class: Mongoid::Document

Inherits:
Object show all
Extended by:
Finders
Includes:
ActiveSupport::Callbacks, Associations, Attributes, Commands, Observable, Validatable
Defined in:
lib/mongoid/document.rb

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Finders

all, count, criteria, find, first, last, method_missing, paginate, select

Methods included from Associations

included

Methods included from Attributes

included

Methods included from Commands

included

Constructor Details

#initialize(attrs = {}) ⇒ Document

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 Mongo::ObjectID string.

Options:

attrs: The attributes Hash to set up the document with.

Example:

Person.new(:title => "Mr", :age => 30)



185
186
187
188
189
190
191
# File 'lib/mongoid/document.rb', line 185

def initialize(attrs = {})
  @attributes = {}.with_indifferent_access
  process(defaults.merge(attrs))
  @new_record = true if id.nil?
  document = yield self if block_given?
  generate_key; document
end

Instance Attribute Details

#association_nameObject

Returns the value of attribute association_name.



8
9
10
# File 'lib/mongoid/document.rb', line 8

def association_name
  @association_name
end

#attributesObject (readonly)

Returns the value of attribute attributes.



9
10
11
# File 'lib/mongoid/document.rb', line 9

def attributes
  @attributes
end

#new_recordObject

Returns the value of attribute new_record.



9
10
11
# File 'lib/mongoid/document.rb', line 9

def new_record
  @new_record
end

#parentObject

Returns the value of attribute parent.



8
9
10
# File 'lib/mongoid/document.rb', line 8

def parent
  @parent
end

Class Method Details

.collectionObject

Returns the collection associated with this Document. If the document is embedded, there will be no collection associated with it.

Returns: Mongo::Collection



23
24
25
26
27
# File 'lib/mongoid/document.rb', line 23

def collection
  raise Errors::InvalidCollection.new(self) if embedded?
  @collection_name ||= self.to_s.demodulize.tableize
  @collection ||= Mongoid.database.collection(@collection_name)
end

.defaultsObject

Returns a hash of all the default values



30
31
32
# File 'lib/mongoid/document.rb', line 30

def defaults
  @defaults
end

.embedded?Boolean

return true if the Document is embedded in another Documnet.

Returns:



35
36
37
# File 'lib/mongoid/document.rb', line 35

def embedded?
  @embedded == true
end

.field(name, options = {}) ⇒ Object

Defines all the fields that are accessable on the Document For each field that is defined, a getter and setter will be added as an instance method to the Document.

Options:

name: The name of the field, as a Symbol. options: A Hash of options to supply to the Field.

Example:

field :score, :default => 0



51
52
53
54
# File 'lib/mongoid/document.rb', line 51

def field(name, options = {})
  set_field(name, options)
  set_default(name, options)
end

.fieldsObject

Returns all the fields for the Document as a Hash with names as keys.



57
58
59
# File 'lib/mongoid/document.rb', line 57

def fields
  @fields
end

.human_nameObject

Returns a human readable version of the class.



62
63
64
# File 'lib/mongoid/document.rb', line 62

def human_name
  name.underscore.humanize
end

.index(name, options = { :unique => false }) ⇒ Object

Adds an index on the field specified. Options can be :unique => true or :unique => false. It will default to the latter.



68
69
70
# File 'lib/mongoid/document.rb', line 68

def index(name, options = { :unique => false })
  collection.create_index(name, options)
end

.instantiate(attrs = {}, allocating = false) ⇒ Object

Instantiate a new object, only when loaded from the database.



73
74
75
76
77
78
79
80
81
82
# File 'lib/mongoid/document.rb', line 73

def instantiate(attrs = {}, allocating = false)
  attributes = attrs.with_indifferent_access
  if attributes[:_id] || allocating
    document = allocate
    document.instance_variable_set(:@attributes, attributes)
    return document
  else
    return new(attributes)
  end
end

.key(*fields) ⇒ Object

Defines the field that will be used for the id of this Document. This set the id of this Document before save to a parameterized version of the field that was supplied. This is good for use for readable URLS in web applications and MUST be defined on documents that are embedded in order for proper updates in has_may associations.



89
90
91
92
# File 'lib/mongoid/document.rb', line 89

def key(*fields)
  @primary_key = fields
  before_save :generate_key
end

.primary_keyObject

Returns the primary key field of the Document



95
96
97
# File 'lib/mongoid/document.rb', line 95

def primary_key
  @primary_key
end

Instance Method Details

#==(other) ⇒ Object

Performs equality checking on the attributes. For now we chack against all attributes excluding timestamps on the object.



127
128
129
130
131
# File 'lib/mongoid/document.rb', line 127

def ==(other)
  return false unless other.is_a?(Document)
  @attributes.except(:modified_at).except(:created_at) ==
    other.attributes.except(:modified_at).except(:created_at)
end

#assimilate(parent, options) ⇒ Object

Introduces a child object into the Document object graph. This will set up the relationships between the parent and child and update the attributes of the parent Document.

Options:

parent: The Document to assimilate with. options: The association Options for the child.

Example:

name.assimilate(person, options)

Returns: The child Document.



147
148
149
# File 'lib/mongoid/document.rb', line 147

def assimilate(parent, options)
  parentize(parent, options.name); notify; self
end

#cloneObject

Clone the current Document. This will return all attributes with the exception of the document’s id and versions.



153
154
155
# File 'lib/mongoid/document.rb', line 153

def clone
  self.class.instantiate(@attributes.except(:_id).except(:versions).dup, true)
end

#idObject Also known as: _id

Get the id associated with this object. This will pull the _id value out of the attributes Hash.



159
160
161
# File 'lib/mongoid/document.rb', line 159

def id
  @attributes[:_id]
end

#id=(new_id) ⇒ Object Also known as: _id=

Set the id



164
165
166
# File 'lib/mongoid/document.rb', line 164

def id=(new_id)
  @attributes[:_id] = new_id
end

#inspectObject

Returns the class name plus its attributes.



194
195
196
# File 'lib/mongoid/document.rb', line 194

def inspect
  "#{self.class.name} : #{@attributes.inspect}"
end

#new_record?Boolean

Returns true is the Document has not been persisted to the database, false if it has. This is determined by the instance variable @new_record and NOT if the object has an id.

Returns:



201
202
203
# File 'lib/mongoid/document.rb', line 201

def new_record?
  @new_record == true
end

#notifyObject

Set the changed state of the Document then notify observers that it has changed.

Example:

person.notify



215
216
217
218
# File 'lib/mongoid/document.rb', line 215

def notify
  changed(true)
  notify_observers(self)
end

#parentize(object, association_name) ⇒ Object

Sets up a child/parent association. This is used for newly created objects so they can be properly added to the graph and have the parent observers set up properly.

Options:

abject: The parent object that needs to be set for the child. association_name: The name of the association for the child.

Example:

address.parentize(person, :addresses)



232
233
234
235
236
# File 'lib/mongoid/document.rb', line 232

def parentize(object, association_name)
  self.parent = object
  self.association_name = association_name
  add_observer(object)
end

#reloadObject

Reloads the Document attributes from the database.



239
240
241
# File 'lib/mongoid/document.rb', line 239

def reload
  @attributes = collection.find_one(:_id => id).with_indifferent_access
end

#rootObject

Return the root Document in the object graph. If the current Document is the root object in the graph it will return self.



245
246
247
248
249
# File 'lib/mongoid/document.rb', line 245

def root
  object = self
  while (object.parent) do object = object.parent; end
  object || self
end

#to_paramObject

Returns the id of the Document, used in Rails compatibility.



252
253
254
# File 'lib/mongoid/document.rb', line 252

def to_param
  id
end

#update(child, clear = false) ⇒ Object

Observe a notify call from a child Document. This will either update existing attributes on the Document or clear them out for the child if the clear boolean is provided.

Options:

child: The child Document that sent the notification. clear: Will clear out the child’s attributes if set to true.

Example:

person.notify_observers(self) will cause this method to execute.

This will also cause the observing Document to notify it’s parent if there is any.



271
272
273
274
275
# File 'lib/mongoid/document.rb', line 271

def update(child, clear = false)
  name = child.association_name
  clear ? @attributes.delete(name) : @attributes.insert(name, child.attributes)
  notify
end

#valid?Boolean

Needs to run the appropriate callbacks the delegate up to the validatable gem.

Returns:



279
280
281
282
283
284
# File 'lib/mongoid/document.rb', line 279

def valid?
  run_callbacks(:before_validation)
  result = super
  run_callbacks(:after_validation)
  result
end