@@ -477,35 +477,65 @@ regular expressions.
477477Defaults
478478--------
479479
480- You can tell a field in Mongoid to always have a default value if nothing has been provided.
481- Defaults are either static values or lambdas/procs.
480+ A field can be configured to have a fixed default value:
482481
483482.. code-block:: ruby
484483
485- class Person
486- include Mongoid::Document
487- field :blood_alcohol_level, type: Float, default: 0.40
488- field :last_drink , type: Time , default: ->{ 10.minutes.ago }
489- end
484+ class Order
485+ include Mongoid::Document
486+
487+ field :state , type: String , default: 'created'
488+ end
490489
491- Be wary that default values that are not defined as lambdas or procs are evaluated
492- at class load time, so the following 2 definitions are not equivalent.
493- (One would probably prefer the second, which is evaluated at document creation time.)
490+ The default value can also be specified as a ``Proc``:
494491
495492.. code-block:: ruby
496493
497- field :dob, type: Time, default: Time.now
498- field :dob, type: Time, default: ->{ Time.now }
494+ class Order
495+ include Mongoid::Document
496+
497+ field :fulfill_by, type: Time, default: ->{ Time.now + 3.days }
498+ end
499499
500- If you want to set a default with a dependency on the document's state, self inside a lambda
501- or proc evaluates to the document instance.
500+ .. note::
501+
502+ Default values that are not ``Proc`` instances are evaluated at class load
503+ time, meaning the following two definitions are not equivalent:
504+
505+ .. code-block:: ruby
506+
507+ field :submitted_at, type: Time, default: Time.now
508+ field :submitted_at, type: Time, default: ->{ Time.now }
509+
510+ The second definition is most likely the desired one, which causes the
511+ time of submission to be set to the current time at the moment of
512+ document instantiation.
513+
514+ To set a default which depends on the document's state, use ``self``
515+ inside the ``Proc`` instance which would evaluate to the document instance
516+ being operated on:
502517
503518.. code-block:: ruby
504519
505- field :intoxicated_at, type: Time, default: ->{ new_record? ? 2.hours.ago : Time.now }
520+ field :fulfill_by, type: Time, default: ->{
521+ # Order should be fulfilled in 2 business hours.
522+ if (7..8).include?(self.submitted_at.hour)
523+ self.submitted_at + 4.hours
524+ elsif (9..3).include?(self.submitted_at.hour)
525+ self.submitted_at + 2.hours
526+ else
527+ (self.submitted_at + 1.day).change(hour: 11)
528+ end
529+ }
530+
531+ When defining a default value as a ``Proc``, Mongoid will apply the default
532+ after all other attributes are set. To have the default be applied before
533+ the other attributes are set, use the ``pre_processed: true`` field option:
534+
535+ .. code-block:: ruby
506536
507- When defining a default value as a proc, Mongoid will apply the default after all other
508- attributes are set. If you want this to happen before the other attributes, set `` pre_processed: true``.
537+ field :fulfill_by, type: Time, default: ->{ Time.now + 3.days },
538+ pre_processed: true
509539
510540
511541.. _field-aliases:
0 commit comments