Form Builder

This page describes how to set up and configure the Form Builder component which provides a way to create a flexible form in KX Dashboards.

With FormBuilder, it is easy to manage the rules governing field visibility, dropdown options, and form validation. This can be done by either:

• Configuring the FormBuilder component properties from the front-end.

• Adding an external kdb function from the back-end.

In either case, it is possible to monitor the form state and react to a user's current input, for example, by showing/hiding certain fields, changing dropdown options or updating validation rules.

The following shows an example of a form built with the Form Builder component.

Set Up a Form Builder

To set up a Form Builder, click-and-drag the component into the workspace and configure the following:

Before set-up, choose whether you want to build and manage the form using the component properties panel or with an external kdb function.

Set Up Using the Properties Panel

1. Click "+Element" under Elements to add an element to the form schema.

2. Set its id, title, and type.

   

3. Add any desired validators.

   

4. Repeat as necessary for each additional form field.

5. Create an empty dictionary view state to keep track of the form state as a user interacts with the form, and add it under either Basics > Form Values or as the output of a State Output "Change" action. See Form State Management for more details.

   

Set Up Using an External Kdb Function

1. Set the Kdb Schema property to a new empty view state parameter of type "dictionary". Repeat for the Form Values property (or use a State Output action instead).

   

2. Create a query data source returning a function that takes at least one argument named "values" and returns a dictionary with two properties, "schema" and "values", as below. More parameters may be added to this function as desired. See the Form Fields section below for more details on how to add more form fields.

   q

   Copy

   {[values]
       / form field definitions
       field1:`type`title`values`default!("list";"Field 1";("option1";"option2");"option1");
       field2:`type`title`validators!("int";"Field 2";enlist"required");
   
       / define form schema
       properties:`field1`field2!(field1;field2);
       schema:`type`title`properties!("group";"A form example";properties);
   
       / update values with any missing properties and set them to null
       values:@[values;(key properties) except (key values);:;`];
   
       / return dictionary defining the form
       `schema`values!(schema;values)
    }

3. In the Data Dialog, set the values argument to the same view state used for the Form Values property (or the same view state used in the State Output on "change" action).

4. Execute the data source, to display results as shown here.

   

5. Click on the Mapping tab in the Results table and add two rows:

   1. In the first row map schema to the Kdb Schema view state created in step 1.

   2. The second row map values to the Form Values view state created in step 1.

      

Once these steps are complete, you have a data source that automatically executes in response to user input. When the user interacts with the form, the Form Values view state changes. This triggers execution of the data source. You can customize the data source to return different schema depending on the state of values. The result is a form that re-renders as desired in response to user input.

Form Structure

Forms are composed of a nested collection of form groups and form fields. Each form field belongs to some form group containing it. Form groups may also be nested in higher-level groups to create more complex forms. A form's top-level group is called its schema.

Form Fields

Form Fields Definition

All form fields have the following properties available from the property panel (if configuring from the front-end), or defined manually in an external kdb function (if configuring from the back-end). See examples below for more details.

• title (required) - The label text used in the form.

• type (required) - Must be set to a valid kdb type. For dropdowns use "list". For form sub-groups, use "group".

• default (optional) - The default value of the field.

• hidden (optional) - If true, the field is hidden on the form.

• disabled (optional) - If true, the field is disabled.

• ignoreOnChange (optional) - If true, the field will not trigger a "change" state output action.

• classes (optional) - Adds the CSS class or classes (separated by spaces) to the field for custom styling.

• validators (optional) - Adds form field validation.

Some field types have extra properties. For fields of type "symbol":

• password (optional) - If true, the "password" html input type is used, which obscures text characters with a dot ("·").

For dropdown fields of type "list", you can set the dropdown values in an external kdb function using the "values" property:

• values (optional) - A kdb list corresponding to the desired dropdown values, or a kdb dictionary with "Value" and "Text" properties.

• forceSelect (optional) - If true, force selection of the first dropdown value.

• multiSelect (optional) - If true, allows the user to select multiple values in the dropdown.

Alternatively, from the front-end you can create specific list items or add a data source to generate them:

Form Fields Examples

A date field with default value "2020-01-31":

Property panel example:

Kdb definition:

dob:`type`title`default!("date";"Date of birth";"2020-01-31");

                    

An int field that is required and must be between 1 and 10 (inclusive):

Property panel example:

Kdb definition:

e:"Quantity must be an integer between 1 and 10 (inclusive)";
qv:`v1`v2!("required";`type`min`max`message!("range";1i;10i;e));
quantity:`type`title`validators!("int";"Quantity";qv);
                    

A dropdown list with multiple value options:

Property panel example for a dropdown list with two values.

Kdb definition:

options:`type`title`values`default!("list";"Options";(`Value`Text!(`value1`value2;`option1`option2));`option1);
                    

Alternatively, a single list can be used to define the `values property:

options:`type`title`values`default!("list";"Options";(`option1`option2);`option1);
                    

A symbol field that checks to make sure only alphanumeric characters have been entered:

Property panel example for a symbol field with a regexp validator checking for alphanumeric characters only.

Kdb definition:

uv:`type`regexp`flags`message!("regexp";"^\\w+$";"ig";"Invalid character");username:`type`title`validators!("symbol";"Username";uv);
                    

Form Groups

Form Groups Definition

All form groups have the following properties available from the property panel (if configuring from the front-end), or defined manually in an external kdb function (if configuring from the back-end). See examples below for more details.

• type (required) - Must be set to "group".

• title (required) - A string equal to the title of the group.

• layout (optional) - If "Row" ("Column") is selected, then its elements are arranged in a row (column) on the form. The default is "Column".

If using kdb to define the group, then you can add elements to it using the `properties property:

• properties - a dictionary whose keys are the ids of any form fields and sub-groups contained in the group, and whose values are those objects.

See the example above on how to set up the form definition with an external kdb function.

Alternatively, if defining the group from the properties panel, simply click the "+ Element" to add an element inside the group.

Form Groups Examples

An example of a form group defined in kdb with the example fields defined above:

properties:`dob`quantity`options`username!(dob;quantity;options;username);
group1:`type`title`properties!("group";"Group1";properties);

An example of a form with two nested groups:

props1:`dob`quantity!(dob;quantity);
props2:`options`username!(options;username);
group1:`type`title`properties!("group";"Group1";props1);
group2:`type`title`properties!("group";"Group2";@[props2;`group1;:;group1]);

This produces the following nested form when group2 is set as the schema of the kdb form definition function:

From the properties panel, the same configuration above is illustrated below:

Form State Management

There are two ways to manage the form state as the user interacts with the form.

• Basics > Form Values: This view state property stores the current form values as a dictionary, regardless of whether the user has clicked "Submit" or if a particular field has the ignoreOnChange property set to true.

• State Output: State Output actions output the current form values as a dictionary in response to specific triggers - output on "Change", output on "Submit", output on "Cancel". If any field has the ignoreOnChange property set to true, then it does not trigger the "Change" action if the user inputs data into that field.

The current form state can be used to update the form schema via an external kdb function or virtual query.

Form Validation

When the user clicks the submit button, the form checks for any input errors. If found, they are shown to the user and submission is halted. The form performs two types of validation:

1. built-in validation, depending on the kdb type of the field

2. custom validation, added to the field's properties

Built-in validation

Built-in validation checks that the user's input matches the correct kdb type as specified in the form field's definition. For example, an form field of type int will automatically throw an error if the user inputs a floating point number:

Custom validation

There are several types of custom validators that can be added to a form field. Multiple validators may be used together. If using kdb to define the form, validators should be defined in the form field's validators property as a dictionary, with each validator stored in the dictionary's values. See the form validation examples below for details.

Validators also have a disabled property that disables the validator if set to true.

Form Validation Examples

A form field name2 that's both required and must match another field with id name1 can be defined with both the required and function validators as below:

name1:`type`title!("symbol";"Name1");
validators:`v1`v2!("required";`type`condition`message!("function";values[`name1]<>values[`name2];"Must match name1"));
name2:`type`title`validators!("symbol";"Name2";validators);

In this case the required validator is checked first, and if that passes, then the match validator is checked. In the example below, it fails:

Form Builder properties

The following sections provides details on how to configure the properties of the Form Builder component.

Basics

Open the Basics properties on the right and configure the properties described in the following table.

Actions

Refer to Actions for further details.

State Output

An optional action, set to a view state parameter to track the interaction state of the user with the form; define as an empty dictionary view state parameter.

Actions

Elements

Configure the properties, described in the following table.

Element(n)

Define Form inputs.

Type

Set kdb type for Form element.

Validators

Select from email, range, required, regexp or url.

Style, Margins, Format

Refer to Style for common settings..

Further Reading

• Navigate Dashboards workspace

• Configure data source connections

• Use view states

• Publish & Export a dashboard