Class: Mongoid::Document

Inherits:
Object show all
Extended by:
Associations
Includes:
ActiveSupport::Callbacks, 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 Associations

belongs_to, has_many, has_one

Methods included from Attributes

#process

Methods included from Commands

included

Constructor Details

#initialize(attributes = {}) ⇒ 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.



189
190
191
192
 
# File 'lib/mongoid/document.rb', line 189

def initialize(attributes = {})
  @attributes = process(fields, attributes)
  generate_key
end

Instance Attribute Details

#association_name ⇒ Object

Returns the value of attribute association_name.



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

def association_name
  @association_name
end

#attributes ⇒ Object (readonly)

Returns the value of attribute attributes.



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

def attributes
  @attributes
end

#parent ⇒ Object

Returns the value of attribute parent.



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

def parent
  @parent
end

Class Method Details

.all(*args) ⇒ Object

Find Documents given the conditions.

Options:

args: A Hash with a conditions key and other options

Person.all(:conditions => { :attribute => "value" })



27
28
29
 
# File 'lib/mongoid/document.rb', line 27

def all(*args)
  find(:all, *args)
end

.collection ⇒ Object

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

Returns: Mongo::Collection



36
37
38
39
40
 
# File 'lib/mongoid/document.rb', line 36

def collection
  return nil if @embedded
  @collection_name = self.to_s.demodulize.tableize
  @collection ||= Mongoid.database.collection(@collection_name)
end

.count(*args) ⇒ Object

Returns a count of matching records in the database based on the provided arguments.

Person.count(:first, :conditions => { :attribute => "value" })



46
47
48
 
# File 'lib/mongoid/document.rb', line 46

def count(*args)
  Criteria.translate(*args).count(self)
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



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

def field(name, options = {})
  @fields ||= HashWithIndifferentAccess.new
  @fields[name.to_s] = Field.new(name.to_s, options)
  define_method(name) { read_attribute(name) }
  define_method("#{name}=") { |value| write_attribute(name, value) }
end

.fields ⇒ Object

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



70
71
72
 
# File 'lib/mongoid/document.rb', line 70

def fields
  @fields
end

.find(*args) ⇒ Object

Find a Document in several different ways.

If a String is provided, it will be assumed that it is a representation of a Mongo::ObjectID and will attempt to find a single Document based on that id. If a Symbol and Hash is provided then it will attempt to find either a single Document or multiples based on the conditions provided and the first parameter.

Person.find(:first, :conditions => { :attribute => "value" })

Person.find(:all, :conditions => { :attribute => "value" })

Person.find(Mongo::ObjectID.new.to_s)



87
88
89
 
# File 'lib/mongoid/document.rb', line 87

def find(*args)
  Criteria.translate(*args).execute(self)
end

.first(*args) ⇒ Object

Find the first Document given the conditions.

Options:

args: A Hash with a conditions key and other options

Person.first(:conditions => { :attribute => "value" })



98
99
100
 
# File 'lib/mongoid/document.rb', line 98

def first(*args)
  find(:first, *args)
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.



104
105
106
 
# File 'lib/mongoid/document.rb', line 104

def index(name, options = { :unique => false })
  collection.create_index(name, options)
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.



113
114
115
116
 
# File 'lib/mongoid/document.rb', line 113

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

.paginate(params = {}) ⇒ Object

Find all documents in paginated fashion given the supplied arguments. If no parameters are passed just default to offset 0 and limit 20.

Options:

params: A Hash of params to pass to the Criteria API.

Example:

Person.paginate(:conditions => { :field => "Test" }, :page => 1, :per_page => 20)

Returns paginated array of docs.



136
137
138
139
140
141
142
143
 
# File 'lib/mongoid/document.rb', line 136

def paginate(params = {})
  criteria = Criteria.translate(:all, params)
  WillPaginate::Collection.create(criteria.page, criteria.offset, 0) do |pager|
    results = criteria.execute(self)
    pager.total_entries = results.size
    pager.replace(results)
  end
end

.primary_key ⇒ Object

Returns the primary key field of the Document



119
120
121
 
# File 'lib/mongoid/document.rb', line 119

def primary_key
  @primary_key
end

.select(*args) ⇒ Object

Entry point for creating a new criteria from a Document. This will instantiate a new Criteria object with the supplied select criterion already added to it.

Options:

args: A list of field names to retrict the returned fields to.

Example:

Person.select(:field1, :field2, :field3)

Returns: Criteria



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

def select(*args)
  Criteria.new(:all, self).select(*args)
end

Instance Method Details

#==(other) ⇒ Object

Performs equality checking on the attributes.

Raises:



165
166
167
168
169
 
# File 'lib/mongoid/document.rb', line 165

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

#collection ⇒ Object

Get the Mongo::Collection associated with this Document.



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

def collection
  self.class.collection
end

#fields ⇒ Object

Get the fields for the Document class.



177
178
179
 
# File 'lib/mongoid/document.rb', line 177

def fields
  self.class.fields
end

#id ⇒ Object

Get the Mongo::ObjectID associated with this object. This is in essence the primary key.



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

def id
  @attributes[:_id]
end

#new_record? ⇒ Boolean

Returns true is the Document has not been persisted to the database, false if it has.

Returns:



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

def new_record?
  @attributes[:_id].nil?
end

#notify ⇒ Object

Notify observers that this Document has changed.



205
206
207
208
 
# File 'lib/mongoid/document.rb', line 205

def notify
  changed(true)
  notify_observers(self)
end

#primary_key ⇒ Object

Return the Document primary key.



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

def primary_key
  self.class.primary_key
end

#read_attribute(name) ⇒ Object

Read from the attributes hash.



211
212
213
 
# File 'lib/mongoid/document.rb', line 211

def read_attribute(name)
  fields[name].value(@attributes[name])
end

#to_param ⇒ Object

Returns the id of the Document



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

def to_param
  id.to_s
end

#update(child) ⇒ Object

Update the document based on notify from child



221
222
223
224
 
# File 'lib/mongoid/document.rb', line 221

def update(child)
  @attributes.insert(child.association_name, child.attributes)
  notify
end

#write_attribute(name, value) ⇒ Object

Write to the attributes hash.



227
228
229
230
 
# File 'lib/mongoid/document.rb', line 227

def write_attribute(name, value)
  @attributes[name] = fields[name].value(value)
  notify
end

#write_attributes(attrs) ⇒ Object

Writes all the attributes of this Document, and delegate up to the parent.



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

def write_attributes(attrs)
  @attributes = attrs
  notify
end