> For the complete documentation index, see [llms.txt](https://docs.digit.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digit.org/health/v2.0/design/architecture/field-app-architecture/ui-packages/forms-engine-package.md).

# Forms Engine Package

## Overview

This document describes the forms\_engine Flutter package. It dynamically renders multi-page forms based on a JSON configuration and is built on top of the digit\_ui\_components package.

***

## Installation

```
dependencies:
  forms_engine:
    git:
      url: https://github.com/egovernments/health-campaign-field-worker-app.git
      path: packages/forms_engine
      ref: delivery_flow
```

Run:

```
flutter pub get
```

***

## Configuration Example

Below is a realistic JSON config that forms\_engine consumes:

```
{
  "name": "DELIVERYFLOW",
  "order": 2,
  "pages": [
      {
      "page": "DeliveryDetails",
      "type": "object",
      "label": "APPONE_REGISTRATION_DELIVERYDETAILS_SCREEN_HEADING",
      "order": 1,
      "navigateTo": { "name": "household-acknowledgement", "type": "template" },
      "properties": [
        {
          "type": "integer",
          "format": "date",
          "fieldName": "dateOfRegistration",
          "label": "APPONE_REGISTRATION_DELIVERYDETAILS_label_dateOfDelivery",
          "systemDate": true,
          "order": 1,
          "includeInForm": true,
          "includeInSummary": true
        },
        {
          "type": "dynamic",
          "format": "custom",
          "fieldName": "resourceCard",
          "label": "APPONE_REGISTRATION_DELIVERYDETAILS_label_resource",
          "enums": [ { "code": "SP1", "name": "SP1" }, { "code": "SP2", "name": "SP2" }, { "code": "AQ1", "name": "AQ1" }, { "code": "AQ2", "name": "AQ2" } ],
          "validations": [{ "type": "required", "value": true, "message": "..._mandatory_message" }],
          "order": 2,
          "includeInForm": true,
          "includeInSummary": true
        },
        {
          "type": "string",
          "format": "dropdown",
          "fieldName": "deliveryComment",
          "schemaCode": "HCM.DELIVERY_COMMENT_OPTIONS_POPULATOR",
          "label": "APPONE_REGISTRATION_BENEFICIARYDETAILS_label_deliveryComments",
          "order": 3,
          "includeInForm": true,
          "includeInSummary": true
        },
        {
          "type": "string",
          "format": "scanner",
          "fieldName": "scanner",
          "label": "APPONE_REGISTRATION_DELIVERYDETAILS_label_scanner",
          "order": 4,
          "includeInForm": true,
          "includeInSummary": true
        }
      ],
      "actionLabel": "APPONE_REGISTRATION_DELIVERYDETAILS_ACTION_BUTTON_LABEL_1",
      "description": "APPONE_REGISTRATION_DELIVERYDETAILS_SCREEN_DESCRIPTION"
    }  ],
  "project": "CMP-2025-07-09-009012",
  "version": 2,
  "disabled": false,
  "isSelected": true
}
```

***

## Schema & Key Concepts

* Root fields:
  * name / order: identifies the flow.
  * pages (array): each element drives one screen.
  * project, version, disabled, isSelected: meta information.
* Page object:
  * page (string): unique key.
  * type: object
  * label, order, description.
  * navigateTo: next flow or template.
  * properties (array): each defines one UI widget / Form component.
* Property fields:
  * type: “object”, “integer”, “string”,” dynamic”, etc.
  * format: how it renders ( date, dropdown, radio, checkbox,scanner, etc.).
  * fieldName: internal form key.
  * label, order, value.
  * enums: for radio button type form component
  * validations: array of rules (required, custom messages).
  * includeInForm / includeInSummary: Hides fields in form or summary pages..
  * systemDate: if true, auto-populates current date.
  * readOnly, hidden, etc.

***

## Usage

Load the form:

```
context.read<FormsBloc>().add(FormsEvent.load(schemas: schemas));
```

Example:&#x20;

```
final arrayJunctionDataSchemaData = arrayJunctionBoxSchemaEntry?['data'];
final arrayJunctionSchemas = jsonEncode(arrayJunctionDataSchemaData);
context.read<FormsBloc>().add(FormsEvent.load(schemas: [arrayJunctionSchemas]));
```

Clear the form:

```
context.read<FormsBloc>().add(
  const FormsEvent.clearForm(schemaKey: 'AssetForm'));
```

Load submitted form Data:

```
BlocListener<FormsBloc, FormsState>(
listener: (context, formState) {
  if (formState is FormsSubmittedState) {
    DigitLoaders.overlayLoader(context: context);

    final formData = formState.formData;
    if (formData.isEmpty) return;
```

* Builds an internal FormGroup for all properties across pages.
* Renders pages in ascending order.
* Shows the action button with actionLabel (fallback to "Submit").
* After the final page, if a summary.enabled, renders summary before calling onSubmit.

***

## Extension Points

1. Custom Property Types: register new format handlers in FieldBuilder.
2. Conditional Flows: wrap and mutate config before passing to the widget.
3. Theming & Styling: leverages digit\_ui\_components theme—override via ThemeData.
4. Validation: uses reactive\_forms under the hood—add global validators or messages.

***

For more details, explore the code in the[ packages/forms\_engine](https://github.com/egovernments/health-campaign-field-worker-app/tree/delivery_flow/packages/forms_engine) directory.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.digit.org/health/v2.0/design/architecture/field-app-architecture/ui-packages/forms-engine-package.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.