JSON Forms

Description

JSON Forms allow you to create complex, data-driven forms using a single control on a UX Component, rather than adding individual controls for every field. They are lightweight, fast, and can be defined using JSON data.

JSON Forms are a control type (introduced in v4.6.5.0) that you can add to a UX Component. JSON Forms appear in the UX Builder toolbox in the Data Controls section of the toolbox.

JSON Forms are an alternative to adding individual controls to a UX. For example, before JSON Forms were introduced, if you wanted a UX component with these input controls, FirstName, LastName, Address, City and State, you would add 5 individual textbox controls to the UX.

However, using JSON Forms you can add a single control to the UX (a JSON Form control), and then you can edit the JSON Form control and add FirstName, LastName, Address, City and State input controls to the JSON Form.

The advantage of this approach is that the UX is much lighter weight (it has 1 control vs. 5 controls) and it is extremely fast. This advantage becomes more pronounced the more controls you have on a UX.

Another benefit of JSON Forms (besides being extremely light weight and fast) is that the form definition can be composed using either server-side code (for example, Xbasic, Python, Node.js), or client-side (JavaScript).

You can also store form definitions in a database.

JSON Form control in the toolbox

UX Component - Login - JSON Form

The sample UX Login component has been rebuilt using JSON Forms. When you create a new login component from a UX you have the option of using individual controls for the login controls, or using a single JSON Form for all of the login controls.

Login Component Style

If you choose to use a JSON Form the resulting UX component has significantly fewer controls (as shown in the image below).

Login Component using a JSON Form

A UX login component built with individual controls has many more controls than the same component built using a JSON Form (as shown in the image below).

Login Component using Individual Controls

Working with JSON data

The reason that JSON Forms are considered to be a Data Control is that, like all other Data Controls, you can use the .getValue() and .setValue() methods to read and write the value in a JSON Form control.

The JSON data in a JSON Form is in JSON format and the definition of the JSON Form is also in JSON format, hence the name of the control type.

For example, consider a simple UX with a basic JSON Form that looks like this:

Simple JSON Form

Always Submit Value Property

A new property is available for controls to ensure that the control submits a value even if the data in the control has not been edited. By default, the JSON form will only submit a value for a control if the control is dirty.

When this property is checked, a value for the control is always submitted.

Always Submit Value Property

Submit Component with Client-side Errors

A new property, Submit component even if has client-side errors, controls whether the UX component submits when validation errors exist.

The default value for this property is now .f.. Validate code in JSON form controls is evaluated to determine if there are client side errors.

UX Validate Property

Include Property

All controls in JSON forms now have an Include property. The Include property is similar to the Show/hide property in that it can be used to show and hide controls.

The difference between the Show/hide property and the Include property is that if a control's Include property returns false, the control is not rendered at all.

In contrast, if a Show/hide property returns false, the control is rendered, but it is not displayed. When the UX is submitted, the JSON data that is submitted will include a property for all hidden controls, but will not include any controls that are not included.

Include Property

JSON Form definition example

The definition for this JSON Form is:

[
    {
        "type": "edit",
        "id": "TEXTBOX_1",
        "data": {
            "from": "First_Name"
        },
        "label": {
            "text": "First Name"
        }
    },
    {
        "type": "edit",
        "id": "TEXTBOX_2",
        "data": {
            "from": "Last_Name"
        },
        "label": {
            "text": "Last Name"
        }
    }
]

Reading values

When you read the data from the above JSON Form (using the .getValue() method), it might look something like this:

{"First_Name":"Fred","Last_Name":"Smith"}

Reading values from individual controls

When you use the .getValue() and .setValue() methods on a JSON Form you are working with JSON data. However, the .getValue() and .setValue() methods can also be used on individual controls in the JSON Form.

For example, in the simple JSON Form above (which has a First Name and Last Name control), if you were to execute this method:

var val = {dialog.object}.getValue('FORM1')

The value in val might be something like:

{"First_Name":"Fred","Last_Name":"Smith"}

But say you wanted the value in the last_name variable, you could use the .getValue() method as follows:

var val = {dialog.object}.getValue("JSONFORM::Form1::last_name")

Setting Values and Dirty State

When you use the .setValue() method to set the value of a control in a JSON Form using the JSONFORM:: syntax, the JSON Form does not automatically go dirty.

There is an optional parameter that can be set to true to force the JSON form to go dirty.

{dialog.object}.setValue('JSONFORM::JForm1::FirstName','Fred',true);

Control name syntax

The syntax for the control name for both the .getValue() and .setValue() methods is:

JSONFORM::form name::variable name

How to build a JSON Form

To add a JSON Form to a UX component, select the [JSONForm] item from the toolbox.

JSON Form toolbox item

This will add a blank JSON Form to the UX component.

Blank JSON Form added to a UX

Then either double-click on the item in the list of UX controls, or click the smart field for the JSONForm properties property in the Property Grid.

Opening JSON Form properties

This will open the JSON Form builder. You add controls (called items) to the JSON Form in much the same way that you add controls to a UX component.

JSON Form builder

To add a control (i.e. item) to the JSON Form, click the Add Item button. This will open a dialog where you can select the control type to add.

Select Control Type dialog

Control type categories

The Select Control Type dialog is divided into sections. The Data Controls section shows all of the controls that are bound to JSON data. These controls can be used to set values in the JSON data created by the JSON Form and to display data values.

The Other Controls category allows you add buttons, HTML, images and custom controls (where you define the control by entering its JSON definition).

Other Controls section

The Containers section allows you add different types of containers to your JSON Form. Containers are used to control the layout of the JSON Form.

Containers section

New Container Options

New Container Options: Two advanced container controls have been added: FreeFormLayout and CSSGrid.

These allow for pixel-perfect control over your form layout using HTML templates or CSS Grids.

See Also

• Learn how to use CSS Grid and FreeForm Containers

The Pre-defined Controls section allows you to add controls that are designed for a specific purpose.

For example, the [List Detail-View Buttons] control will add several buttons to a JSON Form that is being used as the Detail View for a List to save edits made in the JSON Form back to the List, to synchronize the List, etc.

List Detail-View Buttons control

You can add any control type to the Favorites section by right-clicking on the control and then selecting Add to favorites. To remove a control from the Favorites section, right click on the control in the Favorites section and select Remove from favorites.

Favorites section

Another way in which you can create a JSON Form is by using the Quick start genies.

Quick start genies link

Using the Quick Start Genie

When you click on the Quick start genies hyperlink, the following dialog is displayed.

JSON Form quick start genie dialog

The Genie offers several types of quick starts. These are:

• Create form from sample JSON Data

  This option allows you to enter sample JSON data and to create a form that can be used to create or edit JSON data in the same shape as the sample JSON data. The sample JSON data can include nested arrays.

• Quick Input

  This option allows you to enter a list of form controls and optionally specify the control type for each control (if you don't specify a control type, the control will be a textbox).

• Create Form based on List Data

  This option allows you to select a List control in the UX and automatically build a JSON form to match the data structure of the List's data.

• UX Data Binding

  This option applies when the UX is data bound.

• Quick Dialog - Xdialog Format

  This option allows you to convert Xdialog syntax into a JSON Form.

Quick start example

Using the Real-time Preview window

When you are in the JSON Form designer you can open a Preview window to preview your form layout. The Preview window is modeless, which means that you can keep it open while you continue to work on your form design.

The Preview window is also hot - meaning that if you click on a control in the Preview window the focus in the Property Grid will move to the selected control. If you change a property value in the Property Grid, the Preview is automatically updated.

Save JSON Forms to repository

When you are in the JSON Form designer, you can save the form to the Repository (the Repository is a table in a SQL database). You can configure the Repository by going to the Project Settings dialog.

Once you have saved a form definition to the Repository you can load a form from the Repository.

To save a form to the Repository, click the More.. button and select Save JSON form definition in Repository.

Saving a JSON form definition in the Repository

Load JSON Form from repository

You can load a form into the JSON Form designer from the Repository by clicking the More.. button and selecting Load JSON form definition from Repository.

Load JSON Form from Repository (Action Javascript)

At run-time you can load a JSON Form definition from the Repository into a JSON Form control in the UX. To do this, select the JSONForm Control Action when you define an Action Javascript action.

JSONForm Control Action

Then select the Load a saved form definition from the Repository action, and specify the target JSONForm id and the Saved form name.

Load from Repository action settings

Understanding the Layout Property

Every control in a JSON Form has a Layout property that controls how the different parts of the control (i.e. the control itself, its label, its help text, etc.) are rendered. The JSON Form builder has a number of different pre-defined layout styles. You can also create your own named layout styles.

For example, in the image below, the label for field1 is shown above the control, the label for field2 is shown below the control and the label for field3 is shown to the left of the control.

Layout Examples

Item Layout Property

When you click on the smart field for the Layout property, a dialog is opened showing all of the available named layout styles. The styles shown in green are the system styles and they cannot be edited or deleted.

The styles shown in blue are the user-defined styles.

Layout Styles Dialog

To add a new named layout style, select the <ad-hoc> option and then click the Edit button. The builder for the layout definition will then open.

There are two ways to define a new layout:

Simple

Define an HTML template with placeholders for different control parts.

Javascript

Javascript code.

The builder for the Simple mode is shown below.

Layout Builder - Simple Mode

The builder for the Javascript mode is shown below:

Layout Builder - Javascript Mode

Embedding Controls in a JSON Form

You can embed standard UX Controls within a JSON Form. For example, you might have a ViewBox control that you would like to embed in a JSON Form.

To embed a UX control in a JSON Form, edit the JSON form and add an [Embedded] control (from the Data Controls section in the dialog that appears when you click the Add item button) at the location in the form where you want the embedded control to appear.

Embedded Control Item

Embedded Control Configuration

Then specify the id of the control you want to embed by clicking the smart field for the Control id property.

Select Embedded Control Id

When you use .getValue() to get the value of a JSON Form, the embedded control's value is included in the JSON for the JSON Form's value. Similarly, when you use the .setValue() method to set the value of a JSON Form, the value of any embedded controls will also be set.

Display Format

You can define a Display Format for a field in a JSON Form. When the control has focus, the raw data in the form is shown. When the control loses focus, the formatted value is shown. For example, in the images below the formatted date is shown for the n3 field. In the second image, the raw value in the field is shown.

Formatted Value

Raw Value

The following types of Display Formats can be defined:

Character

Numeric

Date

Friendly date

Custom

When you select the Custom option you can define Javascript code to return the formatted value. Your Javascript code can reference the raw data in the field.

For example, you might define the following Javascript code to add a leading $ to the value in the field:

return '$' + v

Auto-suggest and Edit Combo Picklists

The picklist that is displayed for Auto-suggest and Edit Combo controls can now be based on a SQL expression. This allows you to display data from more than one field in the picklist.

For example, if you set the Display field property to:

expn:concatenate(City,', ',Country)

The picklist will display data from the City and Country fields.

Display Field Expression Prefix

Textbox Controls - In-Control Buttons

You can define in-control buttons for textbox controls and all control types that derive from textbox (e.g. edit-combo).

Custom In-Control Buttons Property

To define in-control buttons, check the Custom in-control buttons property and then click the smart field for the In-control buttons definition property.

This will open a dialog where you can define the buttons. You can place the buttons at either the left or right edge of the control, and the buttons can be either an icon or HTML text.

In-Control Buttons Definition Dialog

The image below shows a textbox control with an in-control button (an icon) on the right edge of the control.

Textbox with In-Control Button

Styling Choices for Picklists and Groups

You can now specify a style and classname for the choices displayed by edit-combo, auto-suggest, RadioButtonsGroup, and CheckBoxesGroup controls.

The style or classname can be specified by a function that returns different class names or styles, depending on the data.

For example, you might enter the following value for the style to show the label for Monday in red:

{javascript}function(d) {if(d.html == 'Monday') return 'color:red'; else return 'color:purple;'}

Notice that the function must be prefixed with {javascript} and that the function takes d (an object with an html and value property) as an argument.

Defining Choice Styles

Styled Picklist Example

Fill-in Fields for Edit-combo and Auto-Suggest

When you define fill-in fields in an edit-combo or auto-suggest control, you can now fill in fields in a JSON Form.

Fill-in Fields Configuration

Placeholders

You can now define placeholders for textbox, dropdown, edit-combo, and auto-suggest controls. The placeholder text can be styled by specifying a class name or a style.

Defining Placeholders

The image below shows a textbox control with some placeholder text, styled to appear in blue. As soon as the user starts typing into the field, the placeholder text is removed.

Placeholder Text Example

Integer-Step Control Enhancements

Additional functionality has been added to the Integer-Step control.

You can now:

• specify that the user can type a value into the control (previously you had to use the increment/decrement buttons)

• specify a minimum and maximum value

• specify an increment value (the amount by which the value is changed when an increment/decrement button is clicked).

To set these properties of the Integer-Step control, edit the JSON form, select the Integer-step control and navigate to the Other Properties section of the properties grid.

Integer-Step Control Properties

Date Picker Control Icons

You can now control if a datepicker control should have an icon to open the datepicker. If no icon is shown, clicking anywhere in the control will open the datepicker. If an icon is shown, you can customize the icon.

Datepicker with No Icon

Datepicker with Default Icon

Datepicker with Custom Icon

To set the properties of the datepicker icon, set the properties shown below.

If you have turned on the Show Icon property, you can leave the Icon Name property blank to use the default icon.

Datepicker Properties

RadioButtons, Checkboxes, and Groups

JSON Forms now support three additional control types: RadioButtonsGroup, CheckboxesGroup, and RadioButton.

The RadioButtonsGroup and CheckboxesGroup controls allow you to define a radio button or checkbox control and also specify the choices for the control.

The choices can be static or dynamic. If dynamic, you can specify a SQL query, an Xbasic function, or a Javascript function.

The controls in the group can be laid out horizontally, vertically, or in multiple columns.

Individual RadioButton Controls

The RadioButton control is a single control. It does not have choices. Instead, you must specify the label for each individual control in the Radio Button HTML property.

You can insert as many RadioButton controls into the JSON form as you require. The individual RadioButton controls will behave as a RadioButtonsGroup control as long as you specify the same variable name for each control in the group.

When you define a RadioButton control, you must specify the value that the control will return when selected. The value is set in the Value property in the RadioButton Properties section.

In the image below, the radio buttons for Pick a day are in a RadioButtonsGroup control and the choices have been defined as a static list.

Note also that the radio button for Monday is red. This was done by setting the Choices data style property to this Javascript function:

{javascript}function(d) {if(d.html == 'Monday') return 'color:red'; else return 'color:green;'}

The Married and Single radio buttons are individual RadioButton controls. They behave as a group because they use the same variable name.

Notice that the RadioButtons in this group are separated by the Pick a day control. This is possible because you have the ability to place the individual RadioButton controls at any location on the JSON form.

For example, the value for the Married radio button might be set to married and the value for the Single radio button might be set to single.

RadioButtons and Groups Example

Action Javascript

The JSONForm Control action in Action Javascript offers a number of actions.

JSONForm Control action options

Data Binding

When you create a UX component you can specify that the UX is databound. This allows you to define how fields in a SQL database are bound to controls on the UX.

You can then navigate through the records in the database and make edits to the values shown in the UX and then, when you click the Submit button, your edits are applied to the database.

By default, when you bind a UX to a database, you define individual controls for each field in the SQL table. However you can also use a JSON Form for Data Binding.

See: Data Binding Video

Using the JSON Form Tester

The JSON Form Tester window allows you to experiment with the JSON definition of a JSON Form to see how the form will render.

See: JSON Form Tester Video

Multiple Layouts

Like Lists, ViewBoxes and ControlBars, JSON Forms can have multiple Layouts.

You can use Action Javascript to switch layouts. Select the Selection layout action in the Action type for the JSON Forms action.

Selection layout action

The JavaScript to change layouts is shown below:

var obj = {dialog.object}.getControl('JFORM1'); // get a pointer for JFORM1
obj.uxSelectLayout('DEFAULT');

Paginated Forms

For large forms, you can divide the content into multiple logical pages (creating a "Wizard" style user interface). This involves wrapping controls in Page containers and using specific JavaScript methods to handle navigation.

See Also

• How to create Paginated JSON Forms

See Also

• Data Driven JSON Forms
• List Detail Views
• Responsive Layouts
• Computed and Summary Fields
• .getValue()
• .setValue()
• Learn how to use CSS Grid and FreeForm Containers
• Paginated JSON Forms
• A5Helper_getJSONFormitems_fromDatabase()
• a5wcb_jsonFormItems_from_commands()
• a5Helper_GenerateJSONFormDefinition_From_SampleData()
• {dialog.object}.setJSONFormItems()