Form Builder Configuration - Quick Start Guide

Quick reference for administrators to configure the Form Builder interface.

---

What Is This?

The Form Builder Configuration feature allows you as a Host Administrator to customize which components and features are available in the Form Builder interface. Think of it as a control panel that lets you:

• Simplify the builder by hiding advanced or unused components
• Tailor the interface for different user skill levels
• Control integrations like FYI or payment features
• Create different configurations for internal vs. external use

Why Use It?

Problem: The Form Builder can be overwhelming with too many options for basic users.

Solution: Configure exactly which fields and features your users see, making the builder simpler and more focused for their needs.

Common Scenarios

✅ Hide unused features - Remove FYI integration if you don't use it
✅ Simplify for end users - Show only basic fields for non-technical users
✅ Lock down system fields - Hide ACL and redirect fields from regular builders
✅ Client-specific deployments - Different configurations for different clients

---

Quick Access

1. Login as Host Administrator
2. Go to Administration → Settings → Host Settings
3. Click Form Builder Configuration tab
4. Select configuration file from dropdown
5. Edit JSON in the Monaco Editor
6. Click Save Configuration

---

Configuration Files

File	Purpose	Use Case
config-build.json	Main builder	Full-featured builder for admins and power users
config-buildcustom.json	Embedded builder	Simplified builder for iframe integrations

Note: File names contain "formio" for technical/historical reasons, but this refers to the Form Builder configuration.

---

Common Tasks

Hide FYI Integration

{
  "builder": {
    "groups": {
      "sfafyidynamicfieldtypes": { "visible": false }
    }
  },
  "features": {
    "enableFyiIntegration": false
  },
  "integrations": {
    "fyi": { "enabled": false }
  }
}

Hide System Fields

{
  "builder": {
    "groups": {
      "sfasystem": {
        "visible": false,
        "description": "System fields for admins only"
      }
    }
  }
}

Simplified Builder (Basic Fields Only)

{
  "builder": {
    "groups": {
      "common": {
        "visible": true,
        "components": {
          "sfatextfield": true,
          "sfatextarea": true,
          "sfaselect": true,
          "sfadatetime": true,
          "sfacheckbox": true
        }
      },
      "sfalayout": { "visible": true },
      "other": { "visible": false },
      "sfadvanced": { "visible": false },
      "sfasystem": { "visible": false },
      "sfafyidynamicfieldtypes": { "visible": false }
    }
  }
}

Hide "Data Source Type" Field

{
  "builder": {
    "editForm": {
      "global": {
        "dataSrc": {
          "hidden": true,
          "description": "Prevent changing data source types"
        }
      }
    }
  }
}

---

Component Groups

Group Key	Title	Example Components
common	Common Fields	Text, Number, Select, Date, Checkbox
sfalayout	Layout	Panel, Section, Heading, Divider
other	Other Fields	Email, Link, HTML Element
sfadvanced	Advanced Fields	File Upload, Signature, Nested Form
sfasystem	System Fields	ACL Assignment, System Redirect
sfafyidynamicfieldtypes	FYI Fields	FYI Custom/Standard Fields, Users

---

Visibility Rules

Show Component

"sfatextfield": true

Hide Component

"sfatextfield": false

Hide Entire Group

"common": {
  "visible": false
}

Hide Individual Components in Group

"common": {
  "visible": true,
  "components": {
    "sfatextfield": true,
    "sfanumber": false
  }
}

---

Quick Troubleshooting

Changes Not Appearing

1. Hard refresh browser: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
2. Clear browser cache
3. Check browser console (F12) for errors
4. Verify correct config file was edited

JSON Validation Error

1. Click Format JSON button
2. Check for:
   • Missing commas
   • Missing closing braces } or brackets ]
   • Unquoted property names
   • Single quotes (should be double quotes)

Components Still Visible

1. Verify you're editing the correct file:
   • Main builder: formio-config-build.json
   • Embedded builder: formio-config-buildcustom.json
2. Check group visibility (if group is hidden, component settings don't matter)
3. Ensure "visible": false is properly set

---

Safety Features

✅ Automatic Backups: System creates timestamped backup before each save
✅ JSON Validation: Invalid JSON is rejected before saving
✅ Safe Defaults: If config fails to load, all components remain visible
✅ Real-time: Changes take effect immediately (no restart needed)

Backup Example: formio-config-build.json.backup.20251219120000

---

Best Practices

1. ✅ Test in development first - Never edit production directly
2. ✅ Document your changes - Use description fields
3. ✅ Use global settings - Avoid repeating same setting per component
4. ✅ Keep backups - Save working configurations before major changes
5. ✅ Hard refresh after save - Ensure browser loads new config

---

Console Commands

Open browser console (F12) and run:

// View entire configuration
console.log(JSON.stringify(window.FormioConfig.getAll(), null, 2));

// Check if component is visible
window.FormioConfig.get('builder.groups.common.components.sfatextfield');

// Check if group is visible
window.FormioConfig.get('builder.groups.sfasystem.visible');

// Reload configuration
window.FormioConfig.reload();

---

Example: Production vs Development

Development (Show All Features)

{
  "environment": "development",
  "builder": {
    "groups": {
      "sfasystem": { "visible": true },
      "sfadvanced": { "visible": true }
    },
    "editForm": {
      "global": {
        "dataSrc": { "hidden": false }
      }
    }
  }
}

Production (Hide Advanced Features)

{
  "environment": "production",
  "builder": {
    "groups": {
      "sfasystem": { "visible": false },
      "sfadvanced": { "visible": false }
    },
    "editForm": {
      "global": {
        "dataSrc": { "hidden": true }
      }
    }
  }
}

---

Key Shortcuts in Monaco Editor

Shortcut	Action
Ctrl+Space	Auto-complete suggestions
Ctrl+F	Find
Ctrl+H	Find and replace
Alt+Shift+F	Format document
Ctrl+/	Toggle comment

---

Need More Detail?

📖 Full Guide: Form Builder Configuration Administrator Guide

📁 Technical Docs: Located in wwwroot/assets/formio/ directory

🆘 Support: Check browser console (F12) for detailed error messages

---

Quick Checklist

• [ ] Access Host Settings → Form Builder Configuration
• [ ] Select correct config file (build vs buildcustom)
• [ ] Make JSON changes
• [ ] Click Format JSON (optional but recommended)
• [ ] Click Save Configuration
• [ ] Confirm save operation
• [ ] Hard refresh browser (Ctrl+Shift+R)
• [ ] Test in Form Builder
• [ ] Verify components show/hide as expected

---

Last Updated: December 2024
Version: 1.0