JSON API Forms

Developer Edition

Updated 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 .


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.

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)

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

...

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

Copyright©  Nymphide Lab 2020 - All Rights Reserved 

...