@@ -32,3 +32,143 @@ more, see `Callbacks
3232<{+active-record-docs+}/active_record_callbacks.html>`__ in the
3333Active Record documentation.
3434
35+ Supported Callbacks
36+ -------------------
37+
38+ Mongoid supports the following callbacks on model classes that implement
39+ the :ref:`Document <mongoid-modeling-documents>` module:
40+
41+ - ``after_initialize``
42+ - ``after_build``
43+ - ``before_validation``
44+ - ``after_validation``
45+ - ``before_create``
46+ - ``around_create``
47+ - ``after_create``
48+ - ``after_find``
49+ - ``before_update``
50+ - ``around_update``
51+ - ``after_update``
52+ - ``before_upsert``
53+ - ``around_upsert``
54+ - ``after_upsert``
55+ - ``before_save``
56+ - ``around_save``
57+ - ``after_save``
58+ - ``before_destroy``
59+ - ``around_destroy``
60+ - ``after_destroy``
61+
62+ To learn more about any of the preceding callback types, see the
63+ `ActiveRecord::Callbacks
64+ <https://api.rubyonrails.org/{+rails-8-version-docs+}/classes/ActiveRecord/Callbacks.html>`__
65+ reference in the Rails API documentation.
66+
67+ You can implement a callback both top-level and embedded documents.
68+
69+ .. note:: Callback Invocation Behavior
70+
71+ For efficiency, {+odm+} invokes the callback only on the document
72+ that you performed the persistence action on. This behavior enables
73+ {+odm+} to support large hierarchies and handle optimized atomic
74+ updates efficiently by not invoking callbacks throughout the document
75+ hierarchy.
76+
77+ Take precautions and ensure testability when implementing callbacks for
78+ domain logic, because these designs can lead to unexpected errors when
79+ callbacks in the chain halt execution. We recommend using callbacks for
80+ cross-cutting concerns, such as queueing up background jobs.
81+
82+ Document Callbacks
83+ ------------------
84+
85+ You must implement and register callbacks on your model classes.
86+ You can register a callback by using ordinary methods, blocks and
87+ ``Proc`` objects, or by defining custom callback objects that use
88+ classes or modules.
89+
90+ This example demonstrates how to register callbacks on the ``Contact``
91+ model class in the following ways:
92+
93+ - Includes the ``before_save`` class method which triggers the
94+ ``process_phone`` method before a ``Contact`` instance is saved to
95+ MongoDB. The ``process_phone`` method is defined separately in the class.
96+
97+ - Includes the ``after_destroy`` class method and uses a block to print a
98+ message when a ``Contact`` instance is deleted.
99+
100+ .. literalinclude:: /includes/data-modeling/callbacks.rb
101+ :start-after: start-doc-callback
102+ :end-before: end-doc-callback
103+ :language: ruby
104+ :emphasize-lines: 8, 11-13, 16-18
105+ :dedent:
106+
107+ The following code performs data operations that demonstrate the
108+ callback actions:
109+
110+ .. literalinclude:: /includes/data-modeling/callbacks.rb
111+ :start-after: start-doc-ops
112+ :end-before: end-doc-ops
113+ :language: ruby
114+ :dedent:
115+
116+ Because callback functionality comes from Active Support, you can use
117+ the ``set_callback`` class method syntax to register callbacks, as shown
118+ in the following code:
119+
120+ .. literalinclude:: /includes/data-modeling/callbacks.rb
121+ :start-after: start-doc-set-syntax
122+ :end-before: end-doc-set-syntax
123+ :language: ruby
124+ :dedent:
125+
126+ Association Callbacks
127+ ---------------------
128+
129+ {+odm+} provides the following association callbacks:
130+
131+ - ``after_add``
132+ - ``after_remove``
133+ - ``before_add``
134+ - ``before_remove``
135+
136+ If you register an association callback on your model class, it is
137+ invoked whenever you add or remove a document from any of the following
138+ associations:
139+
140+ - ``embeds_many``
141+ - ``has_many``
142+ - ``has_and_belongs_to_many``
143+
144+ Specify association callbacks as options on the respective association.
145+ You must pass the added or removed document as the parameter to the
146+ specified callback.
147+
148+ The following code demonstrates how to register an association callback
149+ on a ``User`` model class that embeds multiple ``SavedArticle``
150+ instances:
151+
152+ .. literalinclude:: /includes/data-modeling/callbacks.rb
153+ :start-after: start-association-callback
154+ :end-before: end-association-callback
155+ :language: ruby
156+ :emphasize-lines: 8-13
157+ :dedent:
158+
159+ Additional Information
160+ ----------------------
161+
162+ To learn how to prevent {+odm+} from running callbacks, see the
163+ following references in the Active Record documentation:
164+
165+ - `Skipping Callbacks <{+active-record-docs+}/active_record_callbacks.html#skipping-callbacks>`__
166+ - `Suppressing Callbacks <{+active-record-docs+}/active_record_callbacks.html#suppressing-callbacks>`__
167+
168+ To learn about how {+odm+} manages callbacks in transactions, see the
169+ :ref:`mongoid-data-txn` guide.
170+
171+ To learn how to access and change your MongoDB data, see the
172+ :ref:`mongoid-interact-data` guides.
173+
174+ .. TODO Add link to field types guide.
0 commit comments