From 14c3045f35fd7042ba5f712298489caea188f971 Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 12 Dec 2023 17:11:19 +0900 Subject: [PATCH 1/6] docs: add missing "method" --- user_guide_src/source/models/model.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user_guide_src/source/models/model.rst b/user_guide_src/source/models/model.rst index 5481265231e9..b82aee0300d3 100644 --- a/user_guide_src/source/models/model.rst +++ b/user_guide_src/source/models/model.rst @@ -738,7 +738,7 @@ points in the model's execution can be affected, each through a class property: Defining Callbacks ================== -You specify the callbacks by first creating a new class method in your model to use. This class will always +You specify the callbacks by first creating a new class method in your model to use. This class method will always receive a ``$data`` array as its only parameter. The exact contents of the ``$data`` array will vary between events, but will always contain a key named **data** that contains the primary data passed to the original method. In the case of the insert* or update* methods, that will be the key/value pairs that are being inserted into the database. The From 2e7399a4d89ee99b7574581be381b8d5b3dcee43 Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 12 Dec 2023 17:12:11 +0900 Subject: [PATCH 2/6] docs: improve readability --- user_guide_src/source/models/model.rst | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/user_guide_src/source/models/model.rst b/user_guide_src/source/models/model.rst index b82aee0300d3..70e4370df467 100644 --- a/user_guide_src/source/models/model.rst +++ b/user_guide_src/source/models/model.rst @@ -738,12 +738,20 @@ points in the model's execution can be affected, each through a class property: Defining Callbacks ================== -You specify the callbacks by first creating a new class method in your model to use. This class method will always -receive a ``$data`` array as its only parameter. The exact contents of the ``$data`` array will vary between events, but -will always contain a key named **data** that contains the primary data passed to the original method. In the case -of the insert* or update* methods, that will be the key/value pairs that are being inserted into the database. The -main array will also contain the other values passed to the method, and be detailed later. The callback method -must return the original $data array so other callbacks have the full information. +You specify the callbacks by first creating a new class method in your model to use. + +This class method will always +receive a ``$data`` array as its only parameter. + +The exact contents of the ``$data`` array will vary between events, but +will always contain a key named ``data`` that contains the primary data passed to the original method. +In the case +of the **insert*()** or **update*()** methods, that will be the key/value pairs that are being inserted into the database. +The +main ``$data`` array will also contain the other values passed to the method, and be detailed in `Event Parameters`_. + +The callback method +must return the original ``$data`` array so other callbacks have the full information. .. literalinclude:: model/050.php From fe884ad20b43b114ee4af49799b8c4293a28f049 Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 12 Dec 2023 17:25:16 +0900 Subject: [PATCH 3/6] docs: remove unneeded row There is only one delete() method. --- user_guide_src/source/models/model.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/user_guide_src/source/models/model.rst b/user_guide_src/source/models/model.rst index 70e4370df467..cf88a0cad44f 100644 --- a/user_guide_src/source/models/model.rst +++ b/user_guide_src/source/models/model.rst @@ -798,8 +798,7 @@ beforeFind The name of the calling **method**, whether a **singleton** wa - findAll() **limit** = the number of rows to find. **offset** = the number of rows to skip during the search. afterFind Same as **beforeFind** but including the resulting row(s) of data, or null if no result found. -beforeDelete Varies by delete* method. See the following: -- delete() **id** = primary key of row being deleted. +beforeDelete **id** = primary key of row being deleted. **purge** = boolean whether soft-delete rows should be hard deleted. afterDelete **id** = primary key of row being deleted. **purge** = boolean whether soft-delete rows should be hard deleted. From 7fdc425d0cf94687d8a2bbf91f7de3e1fed3a689 Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 12 Dec 2023 17:25:53 +0900 Subject: [PATCH 4/6] docs: decorate method names --- user_guide_src/source/models/model.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/user_guide_src/source/models/model.rst b/user_guide_src/source/models/model.rst index cf88a0cad44f..9b6c67df6a88 100644 --- a/user_guide_src/source/models/model.rst +++ b/user_guide_src/source/models/model.rst @@ -782,36 +782,36 @@ passed to each event: Event $data contents ================= ========================================================================================================= beforeInsert **data** = the key/value pairs that are being inserted. If an object or Entity class is passed to the - insert method, it is first converted to an array. + ``insert()`` method, it is first converted to an array. afterInsert **id** = the primary key of the new row, or 0 on failure. **data** = the key/value pairs being inserted. - **result** = the results of the insert() method used through the Query Builder. + **result** = the results of the ``insert()`` method used through the Query Builder. beforeUpdate **id** = the array of primary keys of the rows being updated. **data** = the key/value pairs that are being updated. If an object or Entity class is passed to the - update method, it is first converted to an array. + ``update()`` method, it is first converted to an array. afterUpdate **id** = the array of primary keys of the rows being updated. **data** = the key/value pairs being updated. - **result** = the results of the update() method used through the Query Builder. + **result** = the results of the ``update()`` method used through the Query Builder. beforeFind The name of the calling **method**, whether a **singleton** was requested, and these additional fields: -- first() No additional fields -- find() **id** = the primary key of the row being searched for. -- findAll() **limit** = the number of rows to find. +- ``first()`` No additional fields +- ``find()`` **id** = the primary key of the row being searched for. +- ``findAll()`` **limit** = the number of rows to find. **offset** = the number of rows to skip during the search. afterFind Same as **beforeFind** but including the resulting row(s) of data, or null if no result found. beforeDelete **id** = primary key of row being deleted. **purge** = boolean whether soft-delete rows should be hard deleted. afterDelete **id** = primary key of row being deleted. **purge** = boolean whether soft-delete rows should be hard deleted. - **result** = the result of the delete() call on the Query Builder. + **result** = the result of the ``delete()`` call on the Query Builder. **data** = unused. beforeInsertBatch **data** = associative array of values that are being inserted. If an object or Entity class is passed to the - insertBatch method, it is first converted to an array. + ``insertBatch()`` method, it is first converted to an array. afterInsertBatch **data** = the associative array of values being inserted. - **result** = the results of the insertbatch() method used through the Query Builder. + **result** = the results of the ``insertbatch()`` method used through the Query Builder. beforeUpdateBatch **data** = associative array of values that are being updated. If an object or Entity class is passed to the - updateBatch method, it is first converted to an array. + ``updateBatch()`` method, it is first converted to an array. afterUpdateBatch **data** = the key/value pairs being updated. - **result** = the results of the updateBatch() method used through the Query Builder. + **result** = the results of the ``updateBatch()`` method used through the Query Builder. ================= ========================================================================================================= Modifying Find* Data From c04a4e71ca6f56b85aaf89ab4dddba84d2ad61e0 Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 12 Dec 2023 17:34:02 +0900 Subject: [PATCH 5/6] docs: make `id` clearer --- user_guide_src/source/models/model.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user_guide_src/source/models/model.rst b/user_guide_src/source/models/model.rst index 9b6c67df6a88..cf9b983d78c4 100644 --- a/user_guide_src/source/models/model.rst +++ b/user_guide_src/source/models/model.rst @@ -798,9 +798,9 @@ beforeFind The name of the calling **method**, whether a **singleton** wa - ``findAll()`` **limit** = the number of rows to find. **offset** = the number of rows to skip during the search. afterFind Same as **beforeFind** but including the resulting row(s) of data, or null if no result found. -beforeDelete **id** = primary key of row being deleted. +beforeDelete **id** = primary key of row being passed to the ``delete()`` method. **purge** = boolean whether soft-delete rows should be hard deleted. -afterDelete **id** = primary key of row being deleted. +afterDelete **id** = primary key of row being passed to the ``delete()`` method. **purge** = boolean whether soft-delete rows should be hard deleted. **result** = the result of the ``delete()`` call on the Query Builder. **data** = unused. From 97c4518a4ac5fd2afa1954fabd10479706cd5320 Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 14 Dec 2023 16:13:53 +0900 Subject: [PATCH 6/6] docs: just joining lines together nicely --- user_guide_src/source/models/model.rst | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/user_guide_src/source/models/model.rst b/user_guide_src/source/models/model.rst index cf9b983d78c4..fdedcc7d15d7 100644 --- a/user_guide_src/source/models/model.rst +++ b/user_guide_src/source/models/model.rst @@ -740,18 +740,17 @@ Defining Callbacks You specify the callbacks by first creating a new class method in your model to use. -This class method will always -receive a ``$data`` array as its only parameter. - -The exact contents of the ``$data`` array will vary between events, but -will always contain a key named ``data`` that contains the primary data passed to the original method. -In the case -of the **insert*()** or **update*()** methods, that will be the key/value pairs that are being inserted into the database. -The -main ``$data`` array will also contain the other values passed to the method, and be detailed in `Event Parameters`_. - -The callback method -must return the original ``$data`` array so other callbacks have the full information. +This class method will always receive a ``$data`` array as its only parameter. + +The exact contents of the ``$data`` array will vary between events, but will always +contain a key named ``data`` that contains the primary data passed to the original +method. In the case of the **insert*()** or **update*()** methods, that will be +the key/value pairs that are being inserted into the database. The main ``$data`` +array will also contain the other values passed to the method, and be detailed +in `Event Parameters`_. + +The callback method must return the original ``$data`` array so other callbacks +have the full information. .. literalinclude:: model/050.php