Skip to content
Aptiwise Documentation

Multi-Page Form YAML Enhancement

Multi-Page Form YAML Enhancement

Section titled “Multi-Page Form YAML Enhancement”

Enhanced Structure Overview

Section titled “Enhanced Structure Overview”
form_definition:
  id: "multipage_purchase_request"
  title: "Purchase Request Workflow"
  type: "multipage"  # NEW: Enables multi-page mode


  # NEW: Page/Step configuration
  pages:
    navigation:
      type: "wizard"           # wizard | tabs | accordion
      showProgress: true       # Progress bar/indicator
      allowSkipBack: true      # Can go to previous pages
      allowSkipForward: false  # Must complete current page
      saveProgress: true       # Auto-save on page navigation


    completion:
      showSummary: true        # Show review page before submission
      allowEdit: true          # Can edit from summary page
      confirmSubmission: true  # Require confirmation dialog


    # Page definitions
    steps:
      - id: "basic_info"
        title: "Basic Information"
        subtitle: "Tell us about your purchase request"
        order: 1
        required: true


      - id: "details"
        title: "Purchase Details"
        subtitle: "Provide detailed information"
        order: 2
        required: true


      - id: "approvals"
        title: "Approval Requirements"
        subtitle: "Specify approval workflow"
        order: 3
        conditional:
          show_if: "amount > 1000"  # Skip for small purchases


      - id: "attachments"
        title: "Supporting Documents"
        subtitle: "Upload receipts and documentation"
        order: 4
        required: false


      - id: "review"
        title: "Review & Submit"
        subtitle: "Confirm your request details"
        order: 5
        type: "summary"         # Special summary page
        required: true


  # Enhanced layout system with page-specific layouts
  layout:
    type: "responsive_grid"
    maxWidth: "800px"         # Narrower for better mobile experience


    # Page-specific layouts
    pages:
      basic_info:
        maxWidth: "600px"      # Smaller for basic info
        sections:
          - id: "requestor_info"
            title: "Requestor Information"
            columns: { desktop: 2, tablet: 2, mobile: 1 }
            fields: ["requestor_name", "department", "email"]


          - id: "request_basics"
            title: "Request Overview"
            columns: { desktop: 1, tablet: 1, mobile: 1 }
            fields: ["item_name", "amount", "urgency"]


      details:
        maxWidth: "900px"      # Wider for detailed info
        sections:
          - id: "item_details"
            title: "Item Specifications"
            columns: { desktop: 2, tablet: 1, mobile: 1 }
            fields: ["category", "brand", "model", "quantity"]


          - id: "business_case"
            title: "Business Justification"
            columns: { desktop: 1, tablet: 1, mobile: 1 }
            fields: ["description", "justification", "business_impact"]


      approvals:
        sections:
          - id: "approval_config"
            title: "Approval Settings"
            columns: { desktop: 1, tablet: 1, mobile: 1 }
            fields: ["approval_type", "special_requirements", "deadline"]


      attachments:
        sections:
          - id: "file_uploads"
            title: "Document Uploads"
            columns: { desktop: 2, tablet: 1, mobile: 1 }
            fields: ["receipt", "quote", "specification", "other_docs"]


      review:
        type: "summary_layout"
        showAllSections: true
        editableInline: false


  # Fields remain the same but with page assignments
  fields:
    # Page 1: Basic Info
    - id: "requestor_name"
      type: "text"
      label: "Your Name"
      page: "basic_info"
      section: "requestor_info"
      required: true
      validation:
        minLength: 2


    - id: "department"
      type: "select"
      label: "Department"
      page: "basic_info"
      section: "requestor_info"
      options:
        - { value: "engineering", label: "Engineering" }
        - { value: "marketing", label: "Marketing" }
        - { value: "sales", label: "Sales" }


    - id: "item_name"
      type: "text"
      label: "Item/Service Name"
      page: "basic_info"
      section: "request_basics"
      required: true


    - id: "amount"
      type: "currency"
      label: "Estimated Cost"
      page: "basic_info"
      section: "request_basics"
      required: true
      validation:
        min: 0.01
        max: 100000


    # Page 2: Details
    - id: "description"
      type: "textarea"
      label: "Detailed Description"
      page: "details"
      section: "business_case"
      required: true
      layout:
        rows: 4


    - id: "justification"
      type: "textarea"
      label: "Business Justification"
      page: "details"
      section: "business_case"
      required: true
      helpText: "Explain why this purchase is necessary"


    # Page 3: Approvals (conditional)
    - id: "approval_type"
      type: "select"
      label: "Approval Type Required"
      page: "approvals"
      section: "approval_config"
      conditional:
        show_if: "amount > 1000"
      options:
        - { value: "standard", label: "Standard Approval" }
        - { value: "expedited", label: "Expedited Approval" }


    # Page 4: Attachments
    - id: "receipt"
      type: "file"
      label: "Receipt/Invoice"
      page: "attachments"
      section: "file_uploads"
      accept: ".pdf,.jpg,.png"
      maxSize: "10MB"


  # NEW: Page validation rules
  validation:
    pageLevel:
      basic_info:
        required: ["requestor_name", "item_name", "amount"]
        custom:
          - rule: "amount > 0"
            message: "Amount must be greater than zero"


      details:
        required: ["description", "justification"]
        custom:
          - rule: "description.length >= 50"
            message: "Description must be at least 50 characters"


      approvals:
        conditional:
          - if: "amount > 5000"
            then:
              required: ["approval_type", "special_requirements"]


  # NEW: Navigation behavior
  navigation:
    buttons:
      previous:
        text: "← Previous"
        style: "secondary"
        showOn: ["details", "approvals", "attachments", "review"]


      next:
        text: "Next →"
        style: "primary"
        showOn: ["basic_info", "details", "approvals", "attachments"]


      submit:
        text: "Submit Request"
        style: "primary"
        showOn: ["review"]
        requireConfirmation: true
        confirmationText: "Are you sure you want to submit this request?"


    progress:
      type: "steps"        # steps | bar | dots
      showLabels: true
      showNumbers: true
      clickable: false     # Can't skip ahead by clicking


  # NEW: Auto-save and data persistence
  persistence:
    autoSave: true
    autoSaveInterval: 30000  # 30 seconds
    storageType: "session"   # session | local | server
    resumable: true          # Can resume incomplete forms


  # Enhanced conditional logic for pages
  conditionalLogic:
    skipRules:
      - if: "amount <= 1000"
        skipPages: ["approvals"]


      - if: "urgency == 'low' && amount <= 500"
        skipPages: ["approvals", "attachments"]
        skipTo: "review"


    showRules:
      - if: "department == 'engineering'"
        showFields: ["technical_specs", "compatibility_check"]
        onPage: "details"


  # NEW: Summary page configuration
  summaryPage:
    groupByPage: true
    showPageTitles: true
    allowInlineEdit: true
    hiddenFields: ["internal_notes"]  # Don't show in summary


    customSections:
      - title: "Request Summary"
        fields: ["item_name", "amount", "urgency"]
        style: "highlight"


      - title: "Business Case"
        fields: ["description", "justification"]
        style: "standard"


      - title: "Attachments"
        fields: ["receipt", "quote"]
        style: "compact"


# AI-Generated Multi-Page Examples


## Example 1: Employee Onboarding (5 Pages)
employee_onboarding:
  type: "multipage"


  pages:
    steps:
      - { id: "personal", title: "Personal Information", order: 1 }
      - { id: "employment", title: "Employment Details", order: 2 }
      - { id: "benefits", title: "Benefits Selection", order: 3 }
      - { id: "documents", title: "Required Documents", order: 4 }
      - { id: "review", title: "Review & Sign", order: 5, type: "summary" }


    navigation:
      type: "wizard"
      saveProgress: true
      showProgress: true


## Example 2: Insurance Claim (Dynamic Pages)
insurance_claim:
  type: "multipage"


  pages:
    steps:
      - { id: "incident", title: "Incident Details" }
      - { id: "damage_auto", title: "Vehicle Damage", conditional: { show_if: "claim_type == 'auto'" } }
      - { id: "damage_property", title: "Property Damage", conditional: { show_if: "claim_type == 'property'" } }
      - { id: "medical", title: "Medical Information", conditional: { show_if: "injuries == true" } }
      - { id: "evidence", title: "Supporting Evidence" }
      - { id: "review", title: "Review Claim", type: "summary" }


## Example 3: Complex Application (Branching Logic)
loan_application:
  type: "multipage"


  conditionalLogic:
    branchingRules:
      - if: "loan_type == 'personal'"
        sequence: ["basic", "income", "assets", "review"]


      - if: "loan_type == 'business'"
        sequence: ["basic", "business_info", "financials", "collateral", "review"]


      - if: "loan_amount > 100000"
        addPages: ["additional_documentation", "collateral_detailed"]


# Implementation Features


## Page Transition Animations
styling:
  transitions:
    pageChange:
      type: "slide"      # slide | fade | none
      duration: 300      # milliseconds
      direction: "horizontal"


## Mobile-Specific Enhancements
responsive:
  mobile:
    navigation:
      showProgress: "dots"  # More compact on mobile
      stickyButtons: true   # Stick next/prev to bottom


    layout:
      padding: "sm"
      maxWidth: "100%"


## Advanced Validation
validation:
  crossPageValidation:
    - rule: "employment.start_date > personal.birth_date + 16*365*24*60*60*1000"
      message: "Employment start date must be after 16th birthday"


  conditionalValidation:
    - if: "claim_type == 'auto'"
      then:
        required: ["vehicle_year", "vehicle_make", "license_plate"]

Key Enhancements Explained

Section titled “Key Enhancements Explained”

1. Page Structure

Section titled “1. Page Structure”
  • Steps Array: Defines each page with order, title, and conditions
  • Navigation Config: Controls how users move between pages
  • Conditional Pages: Pages that appear/disappear based on user input

2. Page-Specific Layouts

Section titled “2. Page-Specific Layouts”
  • Each page can have its own layout configuration
  • Different column counts and styling per page
  • Summary pages have special layout types

3. Enhanced Validation

Section titled “3. Enhanced Validation”
  • Page-level validation: Must pass before proceeding
  • Cross-page validation: Validate data across multiple pages
  • Conditional requirements: Different validation based on user choices

4. Smart Navigation

Section titled “4. Smart Navigation”
  • Auto-save: Preserve progress as user navigates
  • Skip logic: Automatically skip irrelevant pages
  • Resume capability: Users can return to incomplete forms

5. Progress Tracking

Section titled “5. Progress Tracking”
  • Visual progress indicators (steps, bars, dots)
  • Completion percentages
  • Page state management (completed, current, upcoming)

This enhancement maintains backward compatibility with single-page forms while adding powerful multi-page capabilities that rival dedicated form builders like Typeform or Gravity Forms.