Form Builder Configuration Editor - Administrator Guide

Overview

The Form Builder Configuration Editor allows Host administrators to customize the Form Builder interface by controlling which components, groups, and features are available to form creators. This powerful feature enables you to simplify the form building experience, hide advanced features, or customize the interface for different deployment scenarios.

Key Features

• Visual Configuration Editor: Edit Form Builder configuration files directly from the web interface
• Multiple Configuration Files: Manage separate configurations for different builder views
• Real-time Changes: Modifications take effect immediately after saving (no restart required)
• Component Visibility Control: Show or hide specific form components and entire component groups
• Feature Management: Enable or disable integrations like FYI
• Edit Form Customization: Control which fields appear in component edit dialogs
• Safe Editing: Built-in JSON validation and automatic backups
• Monaco Editor: Professional code editor with syntax highlighting and auto-completion

Prerequisites

• Host Administrator Access: You must be logged in as a host administrator
• Permission: Pages_Administration_Host_Settings permission required
• Basic JSON Knowledge: Understanding of JSON format is helpful but not required (the editor validates your changes)

Accessing the Feature

1. Navigate to Host Settings:

   • Log in as a host administrator
   • Go to Administration → Settings → Host Settings

2. Open Form Builder Configuration Tab:

   • Click on the Form Builder Configuration tab
   • The Monaco Editor will load with the current configuration

Configuration Files

The system manages two primary configuration files:

formio-config-build.json

• Used by: Main form builder interface (/Falcon/Forms/Build)
• Purpose: Full-featured builder for administrators and power users
• Default Features:
  • ✅ All component groups visible
  • ✅ System fields (ACL, redirects)
  • ✅ FYI Integration enabled
  • ✅ Merge Value field visible
  • ✅ Autosave enabled
• Use Case: Internal form builders who need access to all features

formio-config-buildcustom.json

• Used by: Embedded form builder for iframes (/Falcon/Forms/BuildCustom)
• Purpose: Simplified builder for embedded scenarios
• Default Features:
  • ✅ Common and layout components
  • ❌ System fields hidden
  • ❌ FYI Integration disabled
  • ❌ Advanced features simplified
  • ❌ Autosave disabled (parent window controls saving)
• Use Case: External integrations or simplified form building

Using the Configuration Editor

Loading a Configuration

1. Select Configuration Type:

   • Use the dropdown at the top to choose which configuration to edit
   • Build Configuration: Main builder
   • BuildCustom Configuration: Embedded builder

2. View Current Settings:

   • The editor will load the selected configuration file
   • Review the JSON structure and current settings

Editing Configuration

The Monaco Editor provides:

• Syntax Highlighting: JSON elements are color-coded
• Auto-completion: Press Ctrl+Space for suggestions
• Error Detection: Invalid JSON is highlighted in red
• Line Numbers: Easy reference to specific sections
• Minimap: Quick navigation for large files

Saving Changes

1. Make Your Edits: Modify the JSON configuration as needed

2. Format JSON (optional):

   • Click the Format JSON button to auto-format your changes
   • This ensures proper indentation and readability

3. Save Configuration:

   • Click the Save Configuration button
   • Confirm the save operation when prompted
   • The system will:
     • Validate your JSON
     • Create a timestamped backup (e.g., formio-config-build.json.backup.20251219120000)
     • Save your changes
     • Display a success message

4. Test Your Changes:

   • Open the form builder in a new tab
   • Verify that your configuration changes are applied
   • The toolbox should reflect your visibility settings

Other Actions

• Reload: Discard unsaved changes and reload from file
• Switch Files: Change between configuration types (warns about unsaved changes)
• Format JSON: Auto-format the JSON for better readability

Configuration Structure

Basic Structure

{
  "version": "1.0.0",
  "environment": "production",
  "builder": {
    "componentVisibility": {
      "enabled": true
    },
    "groups": {
      // Component group settings
    },
    "editForm": {
      // Edit dialog customization
    }
  },
  "features": {
    // Global feature toggles
  },
  "integrations": {
    // Integration settings
  }
}

Available Component Groups

Group Key	Title	Description
common	Common Fields	Text, numbers, dates, selects, checkboxes, radio buttons
sfalayout	Layout	Panels, sections, headings, dividers, labels
other	Other Fields	Email, links, HTML elements, images
sfadvanced	Advanced Fields	File uploads, signatures, nested forms, popup forms
sfasystem	System Fields	ACL assignment, system redirects
sfafyidynamicfieldtypes	FYI Fields	FYI standard fields, custom fields, and users

Common Components

Common Group:

• sfatextfield - Text Field
• sfanumber - Number Field
• sfaselect - Dropdown/Select
• sfadatetime - Date/Time Picker
• sfacheckbox - Single Checkbox
• checkboxesgroup - Checkbox Group
• radiogroup - Radio Button Group
• sfaradioyn - Yes/No Radio
• sfatextarea - Text Area
• addressgroup - Address Group

Layout Group:

• sfapanel - Panel Container
• section - Section Container
• heading - Heading Text
• label - Label Text
• divider - Visual Divider
• helpnotes - Help Text
• summarytable - Summary Table

Advanced Group:

• sfafile - File Upload
• sfasignature - Digital Signature
• nestedform - Nested Form
• popupform - Popup Form
• imageupload - Image Upload

Common Use Cases

Use Case 1: Hide FYI Integration Completely

Scenario: Your deployment doesn't use FYI, and you want to hide all FYI-related fields.

Configuration:

{
  "builder": {
    "groups": {
      "sfafyidynamicfieldtypes": {
        "visible": false,
        "description": "FYI not used in this deployment"
      }
    }
  },
  "features": {
    "enableFyiIntegration": false
  },
  "integrations": {
    "fyi": {
      "enabled": false,
      "loadCustomFields": false,
      "loadStandardFields": false,
      "loadUsers": false
    }
  }
}

Result: FYI group disappears from toolbox, and no FYI API calls are made.

---

Use Case 2: Simplified Builder for End Users

Scenario: You want to provide a simple form builder with only essential fields.

Configuration:

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

Result: Users see only basic input fields and simple layout elements.

---

Use Case 3: Hide System Fields from Regular Users

Scenario: System fields like ACL and Redirect should only be used by administrators.

Configuration:

{
  "builder": {
    "groups": {
      "sfasystem": {
        "visible": false,
        "description": "System fields reserved for administrators"
      }
    }
  }
}

Result: System fields are hidden from the toolbox.

---

Use Case 4: Hide "Data Source Type" in Edit Forms

Scenario: Prevent users from changing dropdown data sources to URLs or custom sources.

Configuration:

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

Result: When editing select, radio, or checkbox components, the "Data Source Type" dropdown is hidden.

---

Use Case 5: Environment-Specific Configurations

Scenario: Show all features in development, but hide advanced features in production.

Development (formio-config-build.json):

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

Production (formio-config-build.json on prod server):

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

Best Practices

1. Test Before Deploying

• ✅ Always test configuration changes in a development or staging environment first
• ✅ Verify the form builder works as expected after changes
• ✅ Test creating and editing forms with the new configuration
• ❌ Don't make untested changes directly in production

2. Document Your Changes

• ✅ Use the description field to document why components are hidden:

  {
    "sfasystem": {
      "visible": false,
      "description": "Hidden per Client XYZ requirements - ticket #12345"
    }
  }

• ✅ Keep notes about client-specific customizations
• ❌ Don't hide components without documenting the reason

3. Use Global Settings

• ✅ Set global defaults that apply to all components:

  {
    "editForm": {
      "global": {
        "dataSrc": { "hidden": true }
      }
    }
  }

• ❌ Avoid repeating the same setting for each component type

4. Safe Default Behavior

The configuration system uses safe defaults:

• ✅ If config file fails to load, all components remain visible
• ✅ Components are visible by default unless explicitly set to false
• ✅ Missing components in config default to visible
• This ensures the form builder always works, even if configuration has issues

5. Backup Strategy

• The system automatically creates timestamped backups before each save
• Example: formio-config-build.json.backup.20251219120000
• ✅ Keep recent backups in case you need to revert
• ✅ Consider periodic manual backups of working configurations
• ✅ Document which configuration was used for major releases

6. Client-Specific Deployments

For different clients, maintain separate configuration files:

# During deployment, copy the appropriate config
# Client A - Full features
cp formio-config.clientA.json formio-config-build.json

# Client B - No FYI
cp formio-config.clientB.json formio-config-build.json

# Client C - Simplified
cp formio-config.clientC.json formio-config-build.json

Troubleshooting

Configuration Not Applied

Problem: You saved changes but the form builder still shows old configuration.

Solutions:

1. Hard refresh the browser: Press Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
2. Clear browser cache: Settings → Privacy → Clear browsing data
3. Check browser console: Press F12 and look for errors in the Console tab
4. Verify file saved: Check file timestamp in wwwroot/assets/formio/
5. Check JSON validity: Use the Format JSON button to verify syntax

JSON Validation Error

Problem: Error message when trying to save: "Invalid JSON format"

Solutions:

1. Use Format JSON button: This will highlight syntax errors
2. Check for common errors:
   • Missing or extra commas
   • Missing closing braces } or brackets ]
   • Unquoted property names
   • Single quotes instead of double quotes
3. Use online validator: Copy/paste your JSON into jsonlint.com
4. Reload last saved version: Click Reload to start over

Components Still Visible After Hiding

Problem: Set component to visible: false but it still appears in toolbox.

Solutions:

1. Check configuration file: Verify you edited the correct config file
   • formio-config-build.json for main builder
   • formio-config-buildcustom.json for embedded builder
2. Verify JSON path: Ensure proper nesting:

   {
     "builder": {
       "groups": {
         "common": {
           "components": {
             "sfatextfield": false  // ← Check this path
           }
         }
       }
     }
   }

3. Check group visibility: If group is hidden, individual components don't matter:

   {
     "common": {
       "visible": false,  // ← This hides entire group
       "components": {
         "sfatextfield": true  // ← This has no effect
       }
     }
   }

Edit Form Fields Not Hiding

Problem: Set editForm.dataSrc.hidden: true but field still shows.

Possible Causes:

1. Form Builder components not rebuilt: The edit form configuration requires a Form Builder rebuild (developer task)
2. Component not updated: The specific component hasn't been updated to use config helper
3. Wrong component type: Check you're using the correct component key (e.g., select not dropdown)

Solutions:

1. Verify configuration is correctly structured
2. Contact development team if feature isn't working as expected
3. Check console for any configuration loading errors

Configuration Loading Errors

Problem: Console shows errors about configuration not loading.

Solutions:

1. Check file path: Verify config files exist in wwwroot/assets/formio/
2. Check permissions: Ensure web server can read the files
3. Check IIS settings: Verify JSON files are served with correct MIME type
4. Review logs: Check application logs for detailed error messages

Security Considerations

Access Control

• ✅ Only Host administrators can access the configuration editor
• ✅ Protected by Pages_Administration_Host_Settings permission
• ✅ All operations are logged with user ID and timestamp
• ❌ Tenant administrators cannot access Host-level configuration

File Security

• ✅ File system access is restricted to wwwroot/assets/formio/ directory only
• ✅ JSON validation prevents corrupted or malicious files
• ✅ Automatic backups enable quick recovery from mistakes
• ✅ Changes are logged for audit purposes

Best Security Practices

1. Limit access: Only give Host Settings permission to trusted administrators
2. Review changes: Periodically review who made configuration changes and why
3. Test in staging: Never test unfamiliar configurations in production first
4. Monitor backups: Ensure backup files are being created properly
5. Document access: Keep records of who has permission to modify configurations

Advanced Configuration Options

Integration Settings

Control third-party integrations:

{
  "integrations": {
    "fyi": {
      "enabled": true,
      "loadCustomFields": true,
      "loadStandardFields": true,
      "loadUsers": false,
      "apiVersion": "v1",
      "endpoints": {
        "users": "/api/services/app/FyiUsers/GetFyiUsersDropdown",
        "customFields": "/api/services/app/FyiCustomFieldTypes/GetFyiCustomFieldTypesForBuilder",
        "standardFields": "/api/services/app/FyiStandardFieldTypes/GetFyiStandardFieldTypesForBuilder"
      }
    }
  }
}

Settings:

• enabled: Master switch for FYI integration
• loadCustomFields: Whether to load FYI custom fields
• loadStandardFields: Whether to load FYI standard fields
• loadUsers: Whether to load FYI users dropdown
• endpoints: API endpoints for data loading

Feature Toggles

Enable or disable specific features:

{
  "features": {
    "enableFyiIntegration": true,
    "enablePayments": true,
    "enableFileUpload": true,
    "maxFileSize": 10485760,
    "allowedFileTypes": [".pdf", ".docx", ".xlsx", ".jpg", ".png"]
  }
}

Validation Settings

Control form validation behavior:

{
  "validation": {
    "enableClientValidation": true,
    "showValidationErrors": true,
    "validateOnBlur": true
  }
}

UI Settings

Customize the builder interface appearance:

{
  "ui": {
    "theme": "default",
    "showFieldNames": false,
    "compactMode": false,
    "language": "en"
  }
}

Debugging Tools

Browser Console Commands

Open browser console (F12) and use these commands:

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

// Check specific setting
window.FormioConfig.get('builder.groups.common.visible');

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

// Check edit form setting
window.FormioConfig.get('builder.editForm.select.dataSrc.hidden');

// Get debug information
console.log(window.FormioConfig.getDebugInfo());

// Force reload configuration
window.FormioConfig.reload().then(config => {
  console.log('Configuration reloaded:', config);
});

Console Log Messages

Look for these messages when the form builder loads:

Success:

[FormIO Config] Loading configuration from: /assets/formio/formio-config-build.json?v=1234567890
[FormIO Config] ✅ Configuration loaded successfully

Warning:

[FormIO Config] ⚠ Configuration file not found, using defaults
[FormIO Config] ⚠ Invalid JSON in config file, using defaults

Error:

[FormIO Config] ❌ Failed to load configuration: [error details]

Getting Help

Documentation Resources

• This Guide: Overview and common use cases for administrators
• README-CONFIG.md: Technical configuration reference (in wwwroot/assets/formio/)
• EDIT-FORM-CONFIG-GUIDE.md: Detailed guide for edit form customization
• SEPARATE-CONFIGS-GUIDE.md: Information about multiple configuration files

Support Channels

If you need help:

1. Check this documentation first
2. Review console errors for specific error messages
3. Test with example configs provided in wwwroot/assets/formio/
4. Contact technical support with:
   • Description of what you're trying to achieve
   • Configuration file contents
   • Browser console error messages
   • Steps to reproduce the issue

Example Configuration Files

Several example configurations are provided in wwwroot/assets/formio/:

• formio-config.example-hide-fyi.json - Disable FYI integration
• formio-config.example-minimal.json - Minimal builder with basic fields only
• formio-config.example-hide-components.json - Examples of hiding specific components
• formio-config.example-show-datasrc.json - Show advanced data source options

Summary

The Form Builder Configuration Editor provides powerful customization capabilities:

✅ Control component visibility - Show or hide any component or group
✅ Customize edit forms - Control which fields appear in edit dialogs
✅ Manage integrations - Enable or disable FYI and other integrations
✅ Multiple configurations - Different settings for main and embedded builders
✅ Safe editing - Validation, backups, and safe defaults
✅ Real-time changes - No application restart required

Quick Start Steps:

1. Navigate to Host Settings → Form Builder Configuration
2. Select the configuration file to edit
3. Make your changes in the Monaco Editor
4. Click Save Configuration
5. Test in the form builder
6. Verify changes are applied

Remember:

• Always test in development first
• Document why you're hiding components
• Keep backups of working configurations
• Use safe defaults (explicit visible: false to hide)
• Hard refresh browser after changes

---

Last Updated: December 2024
Version: 1.0