Using the JSON Form Builder

Working with Form Builder

In Form Builder it is possible to change the structure and element composition of previously created forms. From the Form Builder view you can update a form name, add new form elements, change existing form elements, restructure a form through drag and drop reordering, and inspect different types of form previews.

Figure 1: JSON Form Builder

JSON Form Elements

The sections below provide an overview of how to build and edit a JSON Form using Form Elements. The element bin is on the right side of the form. There you can find all available elements that can be added to a JSON Form.

Figure 2: Layout & Form Elements

Layout Elements

The Layout elements are not used to directly provide an input field, but rather to group elements or provide unique data structures. There are three types:

• Tables store form elements to build repeatable groupings of related form elements. Each element added to a table becomes a column in the table. Once the form is rendered, tables allow rows to be added that are made up of these sub-elements for capturing data.
• Schema Combinations allow a user to combine schemas and group them into options using the schema combinations element.
• Containers store form elements to build logical groupings of related form elements. These sub-elements are rendered vertically.

Form Elements

Form Elements are used to provide fields that capture values on input. There are six types:

• Text Input — Used to capture short string values.
• Text Area — Used to capture long string values.
• Number Input — Used to capture integer or decimal values.
• Checkbox — Used to capture boolean values.
• Dropdown — Used to capture strings from a set of options. Allows the user to select multiple options from a dropdown menu.
• Radio — Used to capture strings from a set of options. Allows the user to generate buttons to choose a single option.
• File Upload — Used to define an input element for file uploads.

Yang Models

Under the Yang Models tab there is a dropdown that contains a list of Yang based models that the systems learns from NSO. Upon selecting a value from the list, the tab populates a list of top level elements in that Yang based model. These elements can be dragged and dropped into the canvas to build forms.

Adding Elements to a JSON Form

The Form Builder canvas is where the JSON form is built by dragging elements onto the "Drop elements here" zone. As the form is being built, it can be previewed and the generated form schemas can be inspected. For example, to add a dropdown option to a JSON form, drag-and-drop the element labeled Dropdown.

Figure 3: Form Builder Canvas

Changing Element Properties

A form element can be edited by hovering over the stacked dots and then clicking the grid icon next to the element name.

Figure 4: Change Element Properties

A Configure dialog will open the available properties for editing a form element. Click Save to retain your changes.

Figure 5: Configure Element Properties

Referenced below is a list of available properties currently supported for each form element. To update the name of a layout element, edit the Label field.

Adding Dropdown Options

There are two methods of adding dropdown options, static and dynamic.

Static Options

To add static options for a dropdown, set the options type to static. Click the + Option button to add items to the draggable list and use the input field to change the value of the dropdown option. Use the drag handle icon to reorganize the list items via drag and drop. Use the trashcan icon to remove an item from the dropdown options.

Figure 6: Static Options Editor

Dynamic Options

To utilize dynamic options for a dropdown, the following fields have to be configured.

The fields that are set in the form configure the HTTP request and the data mapping that will occur when the form is rendered. Follow these steps to configure the request:

1. Select a Method. If POST is selected, then the Request Body field requires input.
2. Input the Base URL.
3. Input the API Route.
4. Click the Make API Call button to view the response from the request.
5. Select the Source Property.
6. Select the Property Key.
7. Click the Query Data button to see a preview of the values that will populate as the dropdown's options.
8. Click the Back button once all configurations have been set.

Figure 7: Dynamic Options Editor

Dynamic Options with Field Dependency

Dynamic dropdowns that use GET calls can replace any query parameter with the output of another field in the form. For example, a dropdown that uses the route /json-forms/forms/:id can replace the value of ":id" by specifying in "Step 4. Variables" (Figure 29) to use a form reference to any other field in the form.

Figure 8: Field Dependency Configuration Step

When the form is rendered, the dropdown options are dependent on the referenced field's value. If the referenced field is changed, dropdown options will automatically update by making client-side API calls using the new value of the referenced field.

Adding Validation

There are two methods of adding validation, pattern and dynamic. These can be used together or independently. Both can be added by clicking the + Validation button on the form elements editor, where this option is enabled.

Figure 9: Validation Editor

Static Validation

To add a pattern validation input a regular expression into the text field labeled Pattern.

Dynamic Validation

To utilize dynamic validation, the following fields have to be configured.

The fields configure the HTTP request and the data mapping that will occur when the form is rendered. Follow these steps to configure the request:

1. Select POST Method and input the Request Body. The Request Body is a mock body for when the request is actually made on during form field input.
2. Input the Base URL.
3. Input the API Route.
4. Click the Make API Call button to see the response from the request.
5. Select the Source Property.
6. Click the Query Data button to see a preview of the boolean value that determines a valid input value.
7. Select the Dynamic Request Body Property to pick which request body property will have its value replaced by the input value being validated.
8. Input the Error Message that is displayed when the input value is invalid.
9. Click the Back button once all configurations have been set.

Adding Schema Combinations

JSON schemas can be combined using a few keywords in JSON Schema. This can be done using keywords like allOf, oneOf, and anyOf. Using the JSON forms canvas, a user can combine schemas and group them into options using the schema combinations element. Using keywords oneOf and anyOf, a user can fill out only one option in the form, whereas using the option allOf allows a user to fill out all the options in the form.

To add a schema combination to the form canvas, drag and drop the Schema Combinations Element from the form elements on the right onto the canvas. Users can add options to this combination by clicking on the Add Option button; different form elements can be dragged and dropped into these options. A schema combination in the form canvas looks as depicted below.

Figure 10: Schema Combination Canvas

To select what type of combination that particular combination should be like, users can click the Format dropdown and one of the three keywords can be selected.

Figure 11: Schema Combination Dropdown

While filling out the form in the renderer, the element renders a dropdown which allows a user to select which dropdown to fill out. Depending on the option selected in the dropdown the sub-schema corresponding to that option is rendered.

Figure 12: Form Preview Option

Adding Yang Model Elements

The top level elements from the YANG model can be seen in the tab on the right side. These elements can be dragged and dropped into the canvas. The elements will hold their properties and names from the Yang definitions when built into forms.

Lists in Yang models get built as tables in JSON forms, and containers in Yang models get built as containers in JSON forms. All the child elements in tables and containers get added to the forms as the tables and containers are dragged and dropped.

Figure 13: Service Models List Preview

Figure 14: Yang Model Based Form

Dynamic References and Behaviors in Yang-Based Forms

Yang Models use xpath expressions for making dynamic references and running validations. JSON forms replicate this in the UI. Dynamic data references defined by leafrefs in Yang are rendered as dropdowns in the JSON forms. Conditional rendering of fields is achieved by evaluating when expressions from Yang-based models, and validations are run upon submitting the forms.

Figure 15: Yang Model Form Preview

Reorder Elements

Any form element can be reordered using the drag handle icon to move it from its original location to a new location and dropping it.

Delete Elements

Click the trash can to delete an element from the form.

Save Form Changes

Click the Save button to capture any changes made to a form.

Preview a Form

As a form is being built, the form can be previewed by clicking the eye icon of the Form Builder canvas.

Figure 16: Form Preview

Inspect the Generated Schemas

To evaluate the underlying data structures that are generated as a form is built, click the Show Form Data button in the footer of the Preview Form dialog. This displays the JSON Schema, UI Schema, Binding Schema, Validation Schema and other schema inputs for the form. Click Show Form to return to preview mode.

Figure 17: Schema Preview