Aptiwise
Aptiwise
Aptiwise DocumentationForm Layout Feature - Implementation CompleteForm Layout Feature Implementation Guide
Getting Started
ApprovalML YAML Syntax ReferenceApproval Types and Step TypesForm LayoutsAI-Generated Layout & Styling YAMLMulti-Page Form YAML Enhancement
User Guide
Workflow Types & Patterns
Markup language

Form Layouts

Form Layouts

Organize your workflow forms into sections with custom grid layouts. This feature is completely optional - workflows without layouts will display fields in a simple list for backwards compatibility.

Basic Layout Structure

form:
  layout:
    sections:
      - id: "section_id"
        title: "Section Title"
        description: "Optional description"
        initial: true  # Show this section during initial submission
        grid:
          - ["field1", "field2"]  # Row with 2 fields
          - ["field3"]  # Row with 1 field (full width)
          - ["field4", "field5", "field6"]  # Row with 3 fields

    # Optional responsive settings
    responsive:
      tablet: 2  # Max columns on tablet
      mobile: 1  # Max columns on mobile

Section Properties

id (required)

Unique identifier for the section. Used to reference sections in workflow steps.

title (required)

Display title shown in the section header with a gradient background.

description (optional)

Optional description displayed below the title to provide context.

initial (optional, default: false)

Set to true to show this section when the requestor creates the workflow. Only fields in initial: true sections are displayed and required to be filled during submission.

grid (required)

Array of arrays defining field layout. Each inner array represents a row, and field names in the array are displayed side-by-side.

Example:

grid:
  - ["name", "email"]           # Two fields side-by-side
  - ["phone"]                   # Single field, full width
  - ["city", "state", "zip"]    # Three fields in one row

Responsive Behavior

Control how layouts adapt to different screen sizes:

responsive:
  tablet: 2  # Maximum 2 columns per row on tablets (641px - 1024px)
  mobile: 1  # Maximum 1 column per row on mobile (<= 640px)

When responsive settings are applied:

  • Desktop: Uses the actual number of fields in each row (up to 6)
  • Tablet: Limits columns to the tablet value
  • Mobile: Limits columns to the mobile value (typically 1 for vertical stacking)

Section Visibility in Workflow Steps

Control which sections are visible and editable at each approval step using view_sections and edit_sections:

workflow:
  manager_approval:
    name: "Manager Approval"
    type: "decision"
    approver: "manager"
    view_sections: ["employee_info"]  # Read-only sections (grayed out)
    edit_sections: ["approval_info"]  # Editable sections
    on_approve:
      continue_to: "hr_final"

  hr_final:
    name: "HR Final Approval"
    type: "decision"
    approver: "hr_manager"
    view_sections: ["employee_info", "approval_info"]  # Can view previous sections
    edit_sections: ["hr_notes"]  # Can edit HR notes section
    on_approve:
      end_workflow: true

Default Behavior

If view_sections and edit_sections are not specified in a workflow step:

  • All sections are displayed in view mode (read-only)

This ensures safe defaults - approvers can see all information but cannot accidentally modify fields unless explicitly allowed.

Complete Example

name: "Employee Onboarding"
description: "Multi-step onboarding process"

form:
  layout:
    sections:
      - id: "personal_info"
        title: "Employee Details"
        description: "To be filled out by the new employee"
        initial: true  # Shown during workflow creation
        grid:
          - ["full_name", "personal_email"]  # 2 columns
          - ["phone_number"]  # Full width
          - ["start_date", "position"]  # 2 columns

      - id: "it_setup"
        title: "IT Equipment Setup"
        description: "IT department will configure equipment"
        grid:
          - ["laptop_choice"]  # Full width
          - ["monitor_request", "keyboard_request", "mouse_request"]  # 3 columns
          - ["additional_software"]  # Full width

      - id: "hr_verification"
        title: "HR Verification"
        description: "HR final verification and employee ID assignment"
        grid:
          - ["employee_id", "company_email"]  # 2 columns
          - ["hr_notes"]  # Full width

    responsive:
      tablet: 2  # Max 2 columns on tablet
      mobile: 1  # Stack vertically on mobile

  fields:
    # Personal Info Fields
    - name: "full_name"
      type: "text"
      label: "Full Name"
      required: true

    - name: "personal_email"
      type: "email"
      label: "Personal Email"
      required: true

    - name: "phone_number"
      type: "text"
      label: "Phone Number"

    - name: "start_date"
      type: "date"
      label: "Start Date"
      required: true

    - name: "position"
      type: "text"
      label: "Position / Title"
      required: true

    # IT Setup Fields
    - name: "laptop_choice"
      type: "radio"
      label: "Laptop Choice"
      display_as: "buttons"
      options:
        - { value: "macbook_pro", label: "MacBook Pro" }
        - { value: "dell_xps", label: "Dell XPS" }
        - { value: "lenovo_thinkpad", label: "Lenovo ThinkPad" }

    - name: "monitor_request"
      type: "checkbox"
      label: "External Monitor"

    - name: "keyboard_request"
      type: "checkbox"
      label: "External Keyboard"

    - name: "mouse_request"
      type: "checkbox"
      label: "External Mouse"

    - name: "additional_software"
      type: "textarea"
      label: "Additional Software Requirements"

    # HR Verification Fields
    - name: "employee_id"
      type: "text"
      label: "Employee ID"
      required: true

    - name: "company_email"
      type: "email"
      label: "Company Email Address"
      required: true

    - name: "hr_notes"
      type: "textarea"
      label: "HR Notes"

workflow:
  it_provisioning:
    name: "IT Provisioning"
    type: "decision"
    approver: "it_support"
    view_sections: ["personal_info"]  # Can view employee details
    edit_sections: ["it_setup"]  # Can edit IT equipment setup
    on_complete:
      continue_to: "hr_finalization"

  hr_finalization:
    name: "HR Finalization"
    type: "decision"
    approver: "hr_manager"
    view_sections: ["personal_info", "it_setup"]  # Can view both previous sections
    edit_sections: ["hr_verification"]  # Can edit HR verification
    on_approve:
      end_workflow: true

Visual Representation

When rendered, sections will appear with:

  1. Section Header - Gradient blue background with:

    • Section title (large, bold)
    • Section description (smaller, gray)
    • "Read-only" badge for view-only sections

  2. Section Content - White background with:

    • Grid-based field layout
    • Responsive column adjustments
    • Proper field spacing

  3. Field States:

    • Editable: Normal input fields with focus states
    • Read-only: Grayed out with pointer-events disabled

Backwards Compatibility

Workflows without the layout section will:

  • Display all fields in a simple vertical list
  • Work exactly as before
  • Require no changes to existing YAML files

Best Practices

  1. Initial Section: Always mark at least one section with initial: true for workflow creation forms

  2. Logical Grouping: Group related fields into sections (e.g., "Personal Info", "Financial Details", "Approval Info")

  3. Responsive Design: Use responsive settings to ensure forms work well on mobile devices

  4. Section Visibility: Use view_sections and edit_sections to:

    • Show previous information to approvers (view)
    • Allow approvers to fill in their specific sections (edit)
    • Maintain data integrity by limiting edit access

  5. Grid Layout:

    • Use 2-3 columns for most forms
    • Use full-width (1 column) for text areas and long text fields
    • Use 3+ columns sparingly (only for very short fields like checkboxes)

  6. Field Names: Ensure all field names in grid arrays exist in the fields list

Validation

The parser automatically validates:

  • Section IDs are unique
  • All field names in grids exist in the fields list
  • All section references in workflow steps exist in the layout
  • Grid structure is valid (arrays of arrays)

Invalid configurations will be caught when uploading the YAML file.

Approval Types and Step Types

Previous Page

AI-Generated Layout & Styling YAML

Next Page

On this page

Form LayoutsBasic Layout StructureSection Propertiesid (required)title (required)description (optional)initial (optional, default: false)grid (required)Responsive BehaviorSection Visibility in Workflow StepsDefault BehaviorComplete ExampleVisual RepresentationBackwards CompatibilityBest PracticesValidation