JSON API Forms
Developer EditionUpdated November 2020 - VERSION 2.2
The Json API Form Widget lets you build a user form with various entry fields that can be sent to an API for updating or inserting records.
Adding a JSON Form to a Page
In order to add a JSON Form to a page, just drop it from the Widget list and double-click on it:
Exemple of JSON Form
For more details about the form fields types and parameters, please check the User’s Forms documentation.
NOTE
If you want to use a Form for updating data, then the form must be placed on a page that is called from a JSON Repeater by passing the record ID. And in the Form Workflow TAB, you must check the “Load Repeater Data” checkbox.
If your server API expects a primary key (id) , then you have to make sure that this field is we’ll added to the Form (it can then be set to read-only or Hidden in order to avoid any user modification of its value)
JSON FORM Workflow
In order to send the form’s data to an API, you must get the following parameters:
Init if the form is placed in a page called from a JSON Repeater, then you can check the “Load Repeater Data” if you want the form to be automatically filled from the Repeater selected line data.
If you select the “Read only Form”, then the data will be loaded but in read-only mode.Triggered Action “Call an API” by default
Api URL. Set the API address (eg https://www.mydomain/myapi)
Method. Depending on your API, you must choose between the POST and GET method.
Data. The format to send to your API, it can be formData (default) or JSON
Success. You can choose here what’s happening when the Form has been submitted: “Back to Previous Page”, “Back to Home Page”, “Clear the Form” (if you want the user to being able to insert many records) or “Test returned value” if you want to check the returned value by using a custom javascript function.
Show Custom Message. An optional message that will be displayed to the user after the data have been successfully sent to the API.
Test the API returned value. If you have chosen to test the value returned by the API, then put the function name here (without parenthesis, eg. myFunction).
The Function Name is cas sensitive.
When you add your function to your custom code, you must declare 2 parameters, the Sender and the Data, for example: function myFunction(e,data) { }Error Custom Message. An optional message that will be displayed if the API can’t be called with success.
Processing Images & Documents sent with the Json API
Images and documents sent with the Json API are converted to a Blob and must be processed on the server side as such.
NOTE
The images are converted to a Blob because the form does not send the image added to the form by the user, but a memory copy which can be rotated if necessary, and which is resized on the client (so you do not have to resample your images server side)
It means that the image/file content is sent with the other variables in a base64 encode form, for example: data:image/jpeg;base64,XXXXXXXX
(Where XXXXXX is the binary content of the file)
NOTE
Regarding images, the field name defined on the Form is not the one sent to the server, for example, if the Field is named my image in the form, the server will receive a variable with the name image-fileinput (-fileinput is added to the field name)
At the server side, you must then extract the data and process it, here is a basic example with PHP:
If the Data are sent as JSON by the form, then you can extract the raw data with the file_get_content function:
Responding to Form Events
Json API Forms allow you to add custom code, that can be done by using form events or by calling a custom Javascript function.
There are 2 events attached to user Forms: onUserFormSuccess and onUserFormError.
You can access to those events by selecting the Form and select the tab Events from the high property panel:
If you double-click on an event, it will load the TB code editor and add the relevant event code to the file custom.js:
Both of the events are including variables:
data: the result returned by the API (the error message for onUserFormError)
form: a js Object reference of the sender Form
status: the status of the request (integer)
xhr: a javascript reference to the XMLHttpRequest object
NOTE
Those 2 events are global, it means that if you have several forms in your app, you must identify the form before doing anything, for example:
Calling a Javascript Function when submitting the Form
When you setup the form workflow, you can also call a javascript function instead of calling the default API Call.
You can call a Javascript function at 2 levels:
1° - Just after the Submit: use that option when you want to get the form content and build your own process without calling the default functions (The function will receive 2 values: the Form object reference, and the Form Data)
An exemple of Form Workflow with “Call a Javascript function")
And and exemple of function called by the form
2° - After the API has returned a result if you want to test the API result and add your own code for testing this result.
An exemple of Form Workflow with the option “Test the Api Returned Value")
And and exemple of function called by the form
