Skip to content

Commit

Permalink
Amends form validation docs
Browse files Browse the repository at this point in the history
Makes slight improvements to the wording in `onValidate`.

Fixes wrong `onValidateEnd` return type description.

@see https://github.com/mautic/mautic/blob/0aaeba2292397926d948d029143a244c9f3f1dc2/app/assets/js/mautic-form-src.js#L485
  • Loading branch information
putzwasser authored Feb 20, 2024
1 parent 48a1679 commit 35a46b9
Showing 1 changed file with 26 additions and 18 deletions.
44 changes: 26 additions & 18 deletions docs/components/tracking_script.rst
Original file line number Diff line number Diff line change
Expand Up @@ -98,25 +98,30 @@ JavaScript Form processing hooks
}
};
If you wish to run additional code before or after submission of the Form, create a ``MauticFormCallback`` object.
In the example code, replace ``replaceWithFormName`` with the name of your Form.
If you wish to run additional code before or after submission of the form, create a ``MauticFormCallback`` object.
In the example code, replace ``replaceWithFormName`` with the name of your form.

``onValidateEnd`` and ``onResponse`` are actions called by ``Form.customCallbackHandler``.

``onValidate()``
================

Called before default Form validation - use it to override the default Form validation.
Called before built-in form validation.
Implement this callback to override the built-in form validation logic.

Return ``True`` to skip the default Form validation and continue with Form processing.
Return ``False`` to skip the default Form validation and prevent the Form submission.
Return ``null`` to execute default Form validation.
Your callbacks return value determines how the form will be processed:

Check warning on line 112 in docs/components/tracking_script.rst

View workflow job for this annotation

GitHub Actions / prose

[vale] reported by reviewdog 🐶 [Google.Will] Avoid using 'will'. Raw Output: {"message": "[Google.Will] Avoid using 'will'.", "location": {"path": "docs/components/tracking_script.rst", "range": {"start": {"line": 112, "column": 53}}}, "severity": "WARNING"}

1. Return ``True`` to skip the built-in form validation and **continue** with form processing.
2. Return ``False`` to skip the built-in form validation and **prevent** the form submission.
3. Return ``null`` to execute built-in form validation and let its logic determine whether to continue with or prevent the form submission.

Returning ``True`` or ``False`` will skip the execution of `onValidateStart`.

Check warning on line 118 in docs/components/tracking_script.rst

View workflow job for this annotation

GitHub Actions / prose

[vale] reported by reviewdog 🐶 [Google.Will] Avoid using 'will'. Raw Output: {"message": "[Google.Will] Avoid using 'will'.", "location": {"path": "docs/components/tracking_script.rst", "range": {"start": {"line": 118, "column": 33}}}, "severity": "WARNING"}

.. code-block:: js
MauticFormCallback['replaceWithFormName'] = {
onValidate: function () {
// before form validation
// executed before built-in form validation
var formIsGood = True;
var dontUpdate = False;
if(dontUpdate){
Expand All @@ -132,29 +137,32 @@ Return ``null`` to execute default Form validation.
``onValidateStart()``
=====================

Called at the beginning of the default Form validation, this receives no values and a return value isn't required and isn't processed.
Called at the beginning of the default form validation, this receives no values and a return value isn't required and isn't processed.

.. warning:: onValidateStart may not get executed if the default Form validation gets handled during the ``onValidate`` callback.
.. warning:: `onValidateStart` will not get executed if you add the ``onValidate`` callback and it returns ``True`` or ``False``.

Check warning on line 142 in docs/components/tracking_script.rst

View workflow job for this annotation

GitHub Actions / prose

[vale] reported by reviewdog 🐶 [Google.Will] Avoid using 'will'. Raw Output: {"message": "[Google.Will] Avoid using 'will'.", "location": {"path": "docs/components/tracking_script.rst", "range": {"start": {"line": 142, "column": 32}}}, "severity": "WARNING"}

.. code-block:: js
MauticFormCallback['replaceWithFormName'] = {
onValidateStart: function () {
// before default validation
// executed before built-in form validation
},
};
``onValidateEnd(formValid)``
============================

Called after all Form validations are complete - either the default validations and/or the ``onValidate`` callback - and before the Form gets submitted.
Receives ``formValid`` to determine if the Form is valid. A return value isn't required and isn't processed.
Called after all form validations are complete - either the default validations and/or the ``onValidate`` callback - and before the form gets submitted.
Receives ``formValid`` to determine if the form is valid.

If this callback returns ``False`` then this prevents submitting the form.

.. code-block:: js
MauticFormCallback['replaceWithFormName'] = {
onValidateEnd: function (formValid) {
// before form submit
// return False; // prevents submitting the form
},
};
Expand Down Expand Up @@ -193,8 +201,8 @@ Called to clear an existing error. Receives ``containerId`` with the id of the e
``onResponse(response)``
========================

Called prior to default Form submission response processing. Receives ``response`` containing the Form submission response.
Return ``True`` to skip the default Form submission response processing.
Called prior to default form submission response processing. Receives ``response`` containing the form submission response.
Return ``True`` to skip the default form submission response processing.

.. code-block:: js
Expand All @@ -207,7 +215,7 @@ Return ``True`` to skip the default Form submission response processing.
``onResponseStart(response)``
=============================

Called at the beginning of the default Form submission response processing. Receives ``response`` containing the Form submission response.
Called at the beginning of the default form submission response processing. Receives ``response`` containing the form submission response.
Return value isn't required and isn't processed.

.. warning:: onResponseStart may not get executed if the default response processing gets handled during the ``onResponse`` callback
Expand All @@ -231,7 +239,7 @@ Return value isn't required and isn't processed.
},
};
Called at the end default Form submission response processing. Receives ``response`` containing the Form submission response.
Called at the end default form submission response processing. Receives ``response`` containing the form submission response.
Return value isn't required and isn't processed.

.. warning:: onResponseEnd may not get executed if the default response processing gets handled during the ``onResponse`` callback
Expand Down Expand Up @@ -287,7 +295,7 @@ Called prior to default enabling of the submit button. Receives no values. Retur

.. vale off
Called prior to going to the next page in the Form. Useful to adjust the DOM prior to making the page visible.
Called prior to going to the next page in the form. Useful to adjust the DOM prior to making the page visible.

.. vale on
Expand All @@ -304,7 +312,7 @@ Called prior to going to the next page in the Form. Useful to adjust the DOM pri

.. vale off
Called prior to going back to a previous page in the Form. Useful to adjust the DOM prior to making the page visible.
Called prior to going back to a previous page in the form. Useful to adjust the DOM prior to making the page visible.

.. vale on
Expand Down

0 comments on commit 35a46b9

Please sign in to comment.