Build a Form

Design a custom module's form using the visual form builder in PEARS.

The form builder is a visual interface for designing the sections, fields, and response options that make up a custom module. It opens when you click Build in the progress panel of a draft version.

TIP: Changes in the form builder are saved automatically. You can use Undo and Redo to reverse or reapply recent changes.

Form Builder Layout

The form builder is organized into three panels:

• Left panel — Lists the module's sections. Use this panel to navigate between sections, or reorder sections to manage the form structure.

• Center panel — Displays a preview of the selected section's form as users will see it.

• Right panel — Shows the properties for the selected field. Use this panel to configure labels, help text, field types, options, and conditions. When no fields are selected, shows the element type picker for adding new fields.

Screenshot: The form builder showing the left panel with sections, the center panel with a live form preview, and the right panel with the element type picker

Working with Sections

Sections organize a module's form into logical groups. Every module starts with a General Info section, which always appears first and contains the standard fields (name, reporting periods, program areas, action plans, site, and unit).

Add a Section

Click the Add Section button in the left panel. Enter a Section Name and an Identifier (slug). The identifier is auto-generated from the name, but can be updated.

Configure a Section

Select a section in the left panel to view its properties:

• Name — The section heading displayed to users.

• Identifier — The section's internal identifier (used in exports).

• Instructions — Optional text displayed at the top of the section to guide users.

• Conditions — Optional rules that control when the section is visible. See Conditional Logic below.

Reorder Sections

Drag sections up or down in the left panel to change their order. The General Info section cannot be moved from the first position.

Delete a Section

Select a section and click the Delete button in the edit pop-up. Deleting a section removes all of its fields.

NOTE: The General Info section cannot be deleted.

Working with Fields

Fields are the individual form elements within a section — text inputs, dropdowns, checkboxes, and more.

Add a Field

After opening a section, select a field type from the right panel. See Field Types for a complete reference of available types and their configuration options.

Screenshot: The right panel showing the field properties for a selected text field, including Display Label, Identifier, Placeholder, Help Text, System Code dropdown, Validation Rules, and Display Rules

Configure a Field

Select a field in the left panel to view its properties in the right panel:

• Label — The field label displayed to users.

• Identifier — The field's internal identifier (used in exports). Auto-generated from the label if not set manually.

• Help Text — Optional instructional text displayed below the field.

• Placeholder — Optional placeholder text displayed inside the field when empty.

• Required — Under "Validation Rules" set the field as required or optional.

• System Code — Optional data classification tag for reporting and analysis.

NOTE: Field identifiers must be unique across all sections in a module version. Certain identifiers are reserved by the system (e.g., name, site, unit, comments, uploads) and cannot be used.

Add Response Options

For Dropdown, Radio, and Checkbox fields, add the response options that users can choose from:

1. Select the field in the left panel.

2. In the right panel, click Add Option.

3. Enter a Label and Value for each option.

4. Drag options to reorder them.

5. Optionally assign a System Code to each option.

Screenshot: The right panel showing Field Choices for a dropdown field with Label and Value columns for each option, drag handles for reordering, and tag icons for assigning system codes

Add Subform Fields

For Subform (Related Entity) fields, add child fields that make up each entry in the repeatable group:

1. Select the subform field in the right panel.

2. Drag elements into the subform to add child fields.

3. Configure each child field's label, identifier, and options.

4. Toggle Display as Table Column to control which child fields appear in the summary table on the form.

Reorder Fields

Drag fields up or down within a section to change their order on the form.

Delete a Field

Select a field and click the Delete button in the top right.

Conditional Logic

Conditional logic allows you to show or hide fields and sections, or make fields required, based on the values of other fields in the form. See Conditional Logic for a detailed guide including supported operators, scope rules, and examples.

To add a basic condition:

1. Select the field or section you want to control.

2. In the right panel, expand the Display Rules section and select Add Display Logic.

3. Select the source field, operator, and value that define when the condition is met.

TIP: Conditions can reference fields in the same section or in the General Info section. See Which Fields Can Be Referenced for full scope rules.

Field Options

The General Information section supports system fields that add standard functionality (e.g. Reporting Periods, Program Areas, etc.). When available, field options appear in the right panel when the field is selected. Toggle settings on or off and configure whether the field is required.

Next Steps

After building the form, proceed to Test a Module to preview the module before publishing.