Module: Mongoid::Touchable::InstanceMethods

Included in:
Document
Defined in:
build/mongoid-7.3/lib/mongoid/touchable.rb

Instance Method Summary collapse

Instance Method Details

#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 record is new_record otherwise true.

Since:

  • 3.0.0



26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'build/mongoid-7.3/lib/mongoid/touchable.rb', line 26

def touch(field = nil)
  return false if _root.new_record?
  current = Time.now
  field = database_field_name(field)
  write_attribute(:updated_at, current) if respond_to?("updated_at=")
  write_attribute(field, current) if field

  # If the document being touched is embedded, touch its parents
  # all the way through the composition hierarchy to the root object,
  # because when an embedded document is changed the write is actually
  # performed by the composition root. See MONGOID-3468.
  if _parent
    # This will persist updated_at on this document as well as parents.
    # TODO support passing the field name to the parent's touch method;
    # I believe it should be read out of
    # _association.inverse_association.options but inverse_association
    # seems to not always/ever be set here. See MONGOID-5014.
    _parent.touch

    if field
      # If we are told to also touch a field, perform a separate write
      # for that field. See MONGOID-5136.
      # In theory we should combine the writes, which would require
      # passing the fields to be updated to the parents - MONGOID-5142.
      sets = set_field_atomic_updates(field)
      selector = atomic_selector
      _root.collection.find(selector).update_one(positionally(selector, sets), session: _session)
    end
  else
    # If the current document is not embedded, it is composition root
    # and we need to persist the write here.
    touches = touch_atomic_updates(field)
    unless touches["$set"].blank?
      selector = atomic_selector
      _root.collection.find(selector).update_one(positionally(selector, touches), session: _session)
    end
  end

  # Callbacks are invoked on the composition root first and on the
  # leaf-most embedded document last.
  # TODO add tests, see MONGOID-5015.
  run_callbacks(:touch)
  true
end