Configuring Record Forms

This document provides guidance for configuring form configuration files within your application's configurable form framework. This framework is dynamic and customizable, designed to capture essential information for various record types. Understanding how to configure these files allows you to tailor forms to meet specific needs for different data collection scenarios.

Overview of Configuration File Structure

The form configuration file is a JavaScript module that exports a JSON object. This object defines the structure, behavior, and appearance of the form, including its fields, tabs, validations, and behaviors. Key components include:

• General Properties: Settings such as form name, type, and CSS classes for styling.
• Messages: Custom messages displayed for various form events (e.g., saving, validation errors).
• Fields: Individual input elements, possibly grouped into sections or tabs, which collect data from the user.

Configuring General Properties

1. name: A unique identifier for the form version.
2. type: Specifies the type of form (e.g., 'rdmp', 'project', 'survey').
3. skipValidationOnSave: Determines whether to skip validation when the save button is pressed. Set to false to enforce validation.

Customizing Messages

Define form event messages within the messages object. These should correspond to keys in your localization files:

messages: {
  "saving": ["@form-saving"],
  "validationFail": ["@form-validation-fail-prefix", "@form-validation-fail-suffix"],
  // Other messages...
}

Defining Fields

The fields array includes objects defining form elements. Each object can specify properties such as:

• class: Field type (e.g., Container, TextArea).
• compClass: Component class rendering the field (e.g., TextBlockComponent).
• viewOnly, editOnly: Visibility flags in different modes.
• definition: Contains field-specific properties like name, label, and validation rules.

Example Field Configuration

{
  class: 'TextArea',
  viewOnly: true,
  definition: {
    name: 'projectDescription',
    label: '@project-description',
    rows: 5,
    cols: 10,
    required: true
  }
}

This example defines a text area field for project descriptions, visible only in view mode and marked as required.

Adding and Configuring Tabs

Use TabOrAccordionContainer classes for sections requiring tabs:

{
  class: "TabOrAccordionContainer",
  compClass: "TabOrAccordionContainerComponent",
  definition: {
    id: "mainTab",
    fields: [ ... ] // Field definitions for this tab
  }
}

Each tab can host a distinct set of fields.

The Publish-Subscribe Mechanism

This pattern enables dynamic form interactions, allowing parts of the form to communicate based on user actions or data entry:

Understanding publish and subscribe

• publish: Used by fields to broadcast data or state changes.
• subscribe: Enables fields to listen for updates from other fields and react accordingly.

Configuring the publish Property

Defines events a field will broadcast, typically residing within the field's definition:

definition: {
  name: 'startDate',
  label: 'Start Date',
  publish: {
    onValueUpdate: {
      modelEventSource: 'valueChanges'
    }
  }
}

Configuring the subscribe Property

Specifies how a field reacts to updates from other fields:

subscribe: {
  'startDate': {
    onValueUpdate: [
      {
        action: 'updateValue',
        actionParams: { minDate: '@startDate' }
      }
    ]
  }
}

Link publish and subscribe to create responsive forms that adapt to user input and maintain data consistency.

Final Steps

Test the configured form thoroughly in your application environment to ensure all fields, validations, and interactions work as expected.

Remember, this form configuration file is a versatile tool for customizing data collection processes across different record types. With careful configuration, you can create user-friendly and comprehensive forms tailored to specific requirements.