Module: Mongoid::Touchable::InstanceMethods

Included in:
Document
Defined in:
lib/mongoid/touchable.rb

Overview

TODO:

Refactor using ActiveSupport::Concern

Used to provide mixin functionality.

Instance Method Summary collapse

Instance Method Details

#_clear_touch_updates(field = nil) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Clears changes for the model caused by touch operation.

Parameters:

  • field (Symbol) (defaults to: nil) —

    The name of an additional field to update.



93
94
95
96
97
 
# File 'lib/mongoid/touchable.rb', line 93

def _clear_touch_updates(field = nil)
  remove_change(:updated_at)
  remove_change(field) if field
  _parent._clear_touch_updates if _touchable_parent?
end

#_gather_touch_updates(now, field = nil) ⇒ Hash<String, Time>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Recursively sets touchable fields on the current document and each of its parents, including the root node. Returns the combined atomic $set operations to be performed on the root document.

Parameters:

  • now (Time) —

    The timestamp used for synchronizing the touched time.

  • field (Symbol) (defaults to: nil) —

    The name of an additional field to update.

Returns:

  • (Hash<String, Time>) —

    The touch operations to perform as an atomic $set.



75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/mongoid/touchable.rb', line 75

def _gather_touch_updates(now, field = nil)
  return if touch_callbacks_suppressed?

  field = database_field_name(field)

  write_attribute(:updated_at, now) if respond_to?("updated_at=")
  write_attribute(field, now) if field

  touches = _extract_touches_from_atomic_sets(field) || {}
  touches.merge!(_parent._gather_touch_updates(now) || {}) if _touchable_parent?
  touches
end

#_run_touch_callbacks_from_root ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Recursively runs :touch callbacks for the document and its parents, beginning with the root document and cascading through each successive child document.



104
105
106
107
108
 
# File 'lib/mongoid/touchable.rb', line 104

def _run_touch_callbacks_from_root
  return if touch_callbacks_suppressed?
  _parent._run_touch_callbacks_from_root if _touchable_parent?
  run_callbacks(:touch)
end

#_touchable_parent? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Indicates whether the parent exists and is touchable.

Returns:



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

def _touchable_parent?
  _parent && _association&.inverse_association&.touchable?
end

#suppress_touch_callbacks ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Suppresses the invocation of touch callbacks, for the class that includes this module, for the duration of the block.

Examples:

Suppress touch callbacks on Person documents:

person.suppress_touch_callbacks { ... }


22
23
24
 
# File 'lib/mongoid/touchable.rb', line 22

def suppress_touch_callbacks
  Touchable.suppress_touch_callbacks(self.class.name) { yield }
end

#touch(field = nil) ⇒ true/false

Note:

This will not autobuild associations if those options are set.

Touch the document, in effect updating its updated_at timestamp and optionally the provided field to the current time. If any belongs_to associations exist with a touch option, they will be updated as well.

Examples:

Update the updated_at timestamp.

document.touch

Update the updated_at and provided timestamps.

document.touch(:audited)

Parameters:

  • field (Symbol) (defaults to: nil) —

    The name of an additional field to update.

Returns:

  • (true/false) —

    false if document is new_record otherwise true.



51
52
53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/mongoid/touchable.rb', line 51

def touch(field = nil)
  return false if _root.new_record?

  begin
    touches = _gather_touch_updates(Time.current, field)
    _root.send(:persist_atomic_operations, '$set' => touches) if touches.present?
    _run_touch_callbacks_from_root
  ensure
    _clear_touch_updates(field)
  end

  true
end

#touch_callbacks_suppressed? ⇒ true | false

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Queries whether touch callbacks are being suppressed for the class that includes this module.

Returns:

  • (true | false) —

    Whether touch callbacks are suppressed.



32
33
34
 
# File 'lib/mongoid/touchable.rb', line 32

def touch_callbacks_suppressed?
  Touchable.touch_callbacks_suppressed?(self.class.name)
end