From 2574773e67d6bb0d91c1cb24f5f336829c315f13 Mon Sep 17 00:00:00 2001
From: Ad Schellevis <ad@opnsense.org>
Date: Thu, 20 Oct 2022 11:38:03 +0200
Subject: [PATCH] Development / JS form control - alhough not in stable yet, it
 doesn't hurt to document
 https://github.com/opnsense/core/commit/528474372b373c720962e5efaad3c7cf6773917a
 in advance. closes https://github.com/opnsense/docs/issues/433

---
 .../development/frontend/view_js_helpers.rst  | 26 +++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/source/development/frontend/view_js_helpers.rst b/source/development/frontend/view_js_helpers.rst
index ef6a4cb1..c928e73b 100644
--- a/source/development/frontend/view_js_helpers.rst
+++ b/source/development/frontend/view_js_helpers.rst
@@ -127,10 +127,36 @@ saveFormToEndpoint
 
 :code:`saveFormToEndpoint(url, formid, callback_ok, disable_dialog, callback_fail)` is the opposite of :code:`mapDataToFormUI()`
 and retrieves the data from the form and sends it to the configured (url) endpoint as json structure.
+Underneath this function uses :code:`getFormData(parent)` defined in `opnsense.js` which is responsible for extracting values from
+different form types such as :code:`<input>` and :code:`<select>` types. When the attributes should be type safe
+(e.g. an *integer* in json format should be presented as :code:`1` and not as :code:`"1"`),
+there is the possibility to "cleanse" the data first using a filter.  In this case define an attribute on the input tag with the name :code:`type_formatter`
+containing the function to call.
+
+
+.. code-block:: html
+
+    <input type="text" type_formatter="my_convert_to_int_function" id="myform.myintval">
+
+Which could be implemented in the form javascript as:
+
+.. code-block:: javascript
+
+    function my_convert_to_int_function(payload)
+    {
+        if (/^[+-]?[0-9]*$/.test(payload)) {
+            return  parseInt(payload);
+        } else {
+            return payload;
+        }
+    }
 
 The response data looks similar to the example data in mapDataToFormUI, but more condensed since selections will
 be returned as single (separated) values, such as :code:`lan,wan` if both options where set.
 
+Using the example with the function above, a valid integer would offer a json object similar to :code:`{"myform": {"myintval": 1}}`,
+unparsable data would look like :code:`{"myform": {"myintval": "1x"}}`, in which case backend validations are able to feedback validation results.
+
 
 ----------------------------
 updateServiceControlUI