Core Concepts

Understanding these core concepts will help you design and build effective forms in Ambience.

Form Definition vs Form Instance vs Form Results

Form Definition

A form definition is the template or blueprint for a form. It defines: - The structure and layout (pages, columns, rows) - Input fields and their properties - Validation rules - Visual styling - Behavior (scripts, rules)

Form definitions are created in the Form Designer and stored in MongoDB. They are reusable templates that can be instantiated multiple times.

Form Instance

A form instance is a runtime occurrence of a form definition. When a user opens a form: 1. The form definition is loaded from the database 2. A form instance is created in the browser 3. The user interacts with this instance 4. Data entered by the user is stored in the instance

In workflow-integrated forms, each workflow instance has its own form instance with its own data.

Form Results

Form results are the submitted data from a form instance. When a user submits a form: - The form data is sent to the server - Validation is performed - Data is processed (ETL chains, workflow events) - Results are stored in MongoDB

Form results can be queried using the form.ReadFormResults ETL step.

Component Hierarchy

Forms are built using a hierarchical component structure:

root
├── page (optional, for multi-page forms)
│   ├── column/columns (layout)
│   │   ├── text-input (input field)
│   │   ├── select (dropdown)
│   │   └── button-bar (action)
│   └── row/rows (layout)
│       └── checkbox (input field)
└── column
    └── ...

Root

Every form has a root component. The root represents the form itself and defines: - Form-level properties (label, width, validation) - Scripts (Before Build, After Build, Submit) - Internationalization settings - Custom CSS

Blocks

Blocks are layout containers that structure the form. They don’t display data but organize other components:

  • Page - Creates multi-page forms
  • Column/Columns - Vertical layout sections
  • Row/Rows - Horizontal layout sections
  • Panel - Collapsible sections
  • Tab Bar/Tab Panel - Tabbed interfaces
  • Modal Dialog - Popup dialogs
  • Repeater - Dynamic repeated sections
  • Cascade Group - Cascading selections

Inputs

Inputs are components that collect data from users:

  • Text inputs (single-line, multi-line, formatted, regex)
  • Selection inputs (dropdown, radio, checkbox, multi-select)
  • Date/time inputs (date, year)
  • Dataset inputs (dataset select, picker, chooser, multi-select, checkbox)
  • Special inputs (user chooser, form select)

Actions

Actions are components that trigger operations:

  • Button - Single action button
  • Button Bar - Multiple buttons (Submit, Cancel, etc.)
  • Render DocX/RML - Report generation buttons

Outputs

Outputs display information to users:

  • Alert - Warning/error/info messages
  • Derived Text - Calculated display values

Others

Special-purpose components:

  • Workflow State - Workflow integration
  • Hidden - Store invisible data
  • HTML - Custom HTML content
  • IFrame - Embed external content
  • Image - Display images
  • Attachments - File uploads
  • History - Display workflow history
  • Form Launcher - Launch child forms
  • Vertical Space - Add spacing

Design-Time vs Runtime

Design-Time

Design-time is when you’re building the form in the Form Designer: - Drag and drop components - Configure properties - Define rules - Write scripts - Test the form

Changes are saved to the form definition in MongoDB.

Runtime

Runtime is when users interact with the form: - Form definition is loaded - Form is rendered in the browser (Scala.js) - User enters data - Rules are evaluated - Scripts execute - Validation occurs - Data is submitted

Client-Side vs Server-Side

Forms use a client-server architecture:

Client-Side (Browser)

Built with Scala.js, the client handles: - Form rendering and display - User interaction - Rule evaluation (show/hide, enable/disable) - Client-side validation - Script execution (Before Build, After Build) - Auto-save functionality

Server-Side (JVM)

Built with Scala, the server handles: - Form definition storage and retrieval - Server-side validation - ETL chain execution - Workflow integration - Form submission processing - File upload handling - Access control

Data Flow

Understanding how data flows through a form:

1. User opens form
   ↓
2. Server loads form definition
   ↓
3. Server augments form (I18N, server-side data)
   ↓
4. Client renders form
   ↓
5. User enters data
   ↓
6. Client evaluates rules (show/hide fields)
   ↓
7. User submits form
   ↓
8. Client validation
   ↓
9. Server receives submission
   ↓
10. Server validation (ETL)
    ↓
11. ETL processing
    ↓
12. Workflow event (if integrated)
    ↓
13. Store results
    ↓
14. Return response (redirect, error, success)

Rule Engine

The rule engine evaluates conditions and performs actions dynamically:

Conditions

Rules check conditions like: - Field values (employeeName == "John") - User properties (${username} == "admin") - Roles and privileges (${roles} contains "Manager")

Actions

When conditions are met, rules can: - Show/hide components - Enable/disable components - Make fields mandatory/optional - Navigate to different pages

Evaluation

Rules are evaluated: - When the form loads - When field values change - When user properties are available

Validation Pipeline

Forms support multiple validation layers:

1. Client-Side Validation

Immediate feedback in the browser: - Mandatory field checks - Input type validation (email, number) - Regex pattern matching - Custom script validation

2. Server-Side Validation

Before processing submission: - ETL chainset validation - Business rule validation - Data integrity checks

3. ETL-Based Validation

Custom validation logic: - Complex business rules - Database lookups - External system checks - Multi-field validation

Validation chainsets must include a Validation Endpoint step to be recognized by forms.

Script Execution Model

Forms support three script types:

Before Build Script

Executes before the form is rendered: - Modify form structure - Set initial values - Configure components dynamically

After Build Script

Executes after the form is rendered: - Modify the DOM - Attach event listeners - Initialize third-party libraries

Submit Script

Executes when a button is clicked: - Custom submission logic - Client-side processing - Navigation control

Scripts have access to: - Form data - Component references - User context - Browser APIs

Form State Management

Forms maintain state throughout their lifecycle:

Local State

Stored in the browser: - Current field values - Validation errors - UI state (expanded panels, current page) - Auto-saved drafts (localStorage)

Server State

Stored in MongoDB: - Form definition - Submitted results - Workflow data (elxPublic, elxPrivate) - Attachments

Workflow State

For workflow-integrated forms: - Current workflow state - Workflow history - Public data (visible to form) - Private data (server-only)

Component Properties

Every component has properties that control its behavior:

Common Properties

  • Id - Unique identifier (used in data, rules, scripts)
  • Label - Display text
  • Mandatory Field - Required for submission
  • Disabled - Prevent user interaction
  • Hidden - Hide from view

Input-Specific Properties

  • Default Value - Initial value
  • Placeholder - Hint text
  • Validation - Custom validation rules
  • Min/Max - Value constraints

Layout Properties

  • Width - Component width
  • Alignment - Text alignment
  • Spacing - Margins and padding
  • CSS Classes - Custom styling

Internationalization (I18N)

Forms support multiple languages:

Base I18N

Default translations provided by the system.

Custom I18N

Your own translations for: - Field labels - Validation messages - Button text - Help text

Language Resolution

  1. Check user’s preferred language
  2. Check browser language
  3. Fall back to base I18N
  4. Fall back to English

Access Control

Forms support fine-grained access control:

Privileges

  • mod-form - View forms
  • mod-form-edit - Edit form metadata
  • mod-form-designer - Access Form Designer

Roles

Forms can be restricted to specific roles. Users must have at least one assigned role to access the form.

Workgroups

Forms can be associated with workgroups for multi-tenancy. Users only see forms in their workgroups.

Component-Level Access

Use rules to show/hide components based on: - User roles - User privileges - User properties - Data values

Next Steps

Next: Form Management