Custom Form Builder View - User Guide

Overview

The Custom Form Builder View is a specialized version of the Syntaq.Falcon form builder designed for integration into external systems via iFrames. This guide explains how to use and integrate this feature.

Features

Key Differences from Standard Builder

• Save & Close Button: Instead of "Save & Open", the button says "Save & Close"
• iFrame Optimized: Designed specifically for embedded use
• Parent Communication: Automatically communicates with parent window
• Simplified Interface: Streamlined for iframe context

Integration Guide

Basic iFrame Integration

<iframe 
    src="https://your-syntaq-domain.com/Falcon/Forms/BuildCustom?OriginalId=form-guid"
    width="100%" 
    height="800px"
    frameborder="0"
    allowfullscreen>
</iframe>

Parent Window Message Handling

// Listen for messages from the form builder
window.addEventListener('message', function(event) {
    // Optional: Validate origin for security
    // if (event.origin !== 'https://your-syntaq-domain.com') return;
    
    const message = event.data;
    
    switch(message.type) {
        case 'formBuilderReady':
            console.log('Form builder is ready:', message.formId);
            break;
            
        case 'formSaved':
            console.log('Form saved successfully:', message.formId);
            // Handle successful save - close modal, update UI, etc.
            handleFormSaved(message);
            break;
            
        case 'formSaveError':
            console.error('Form save failed:', message.error);
            // Handle save error - show user message, etc.
            handleFormSaveError(message);
            break;
            
        case 'formBuilderClosed':
            console.log('Form builder closed');
            // Handle builder closure
            handleBuilderClosed(message);
            break;
    }
});

function handleFormSaved(message) {
    // Update your UI to reflect the saved form
    // Close the iframe or modal
    // Continue with your workflow
    console.log('Form saved:', message.formId);
}

function handleFormSaveError(message) {
    // Show error message to user
    alert('Failed to save form: ' + message.error);
}

function handleBuilderClosed(message) {
    // Clean up any resources
    // Update UI state
    console.log('Builder closed');
}

Usage Workflow

1. Opening the Builder

1. Navigate to your external system
2. Click "Create Form" or "Edit Form"
3. The form builder opens in an iframe
4. You'll receive a formBuilderReady message

2. Building the Form

1. Use the form builder interface as normal
2. Add components, configure settings
3. Preview your form using the Preview tab
4. All changes are tracked in real-time

3. Saving and Closing

1. Click the "Save & Close" button
2. The form is saved to Syntaq.Falcon
3. A success message is sent to the parent window
4. The iframe closes automatically

Message Types

formBuilderReady

Sent when the builder interface is fully loaded.

{
    type: "formBuilderReady",
    status: "ready",
    formId: "guid",
    originalId: "guid",
    version: 1,
    timestamp: "2025-01-XX"
}

formSaved

Sent when a form is successfully saved.

{
    type: "formSaved",
    status: "success",
    formId: "guid",
    originalId: "guid",
    version: 1,
    timestamp: "2025-01-XX"
}

formSaveError

Sent when a save operation fails.

{
    type: "formSaveError",
    status: "error",
    error: "Error description",
    timestamp: "2025-01-XX"
}

formBuilderClosed

Sent when the builder interface is closed.

{
    type: "formBuilderClosed",
    status: "closed",
    timestamp: "2025-01-XX"
}

Security Considerations

Origin Validation

For enhanced security, validate the message origin:

window.addEventListener('message', function(event) {
    // Only accept messages from your Syntaq domain
    if (event.origin !== 'https://your-syntaq-domain.com') {
        console.warn('Rejected message from unauthorized origin:', event.origin);
        return;
    }
    
    // Process the message
    handleMessage(event.data);
});

Authentication

• Users must be authenticated in Syntaq.Falcon
• Authentication is maintained across the iframe boundary
• Session timeouts are handled gracefully

Error Handling

Common Error Scenarios

Network Errors

• Symptom: Save operation fails with network error
• Solution: Check internet connection and retry
• User Experience: Error message displayed, button re-enabled

Authentication Errors

• Symptom: User session expired
• Solution: Redirect to login page
• User Experience: Clear error message with login link

Validation Errors

• Symptom: Form validation fails
• Solution: Fix form structure and retry
• User Experience: Specific error messages for each issue

Error Recovery

1. Automatic Retry: Some errors can be retried automatically
2. Manual Retry: User can click "Save & Close" again
3. Graceful Degradation: If communication fails, form still saves locally

Best Practices

For Developers

1. Always handle all message types - Don't ignore any messages
2. Validate message origin - For production environments
3. Provide user feedback - Show loading states and error messages
4. Test cross-browser compatibility - Especially for iframe communication

For Users

1. Save frequently - Don't lose work due to session timeouts
2. Check preview - Always preview your form before saving
3. Use descriptive names - Make forms easy to identify later

Troubleshooting

Builder Won't Load

• Check URL: Ensure the iframe src URL is correct
• Check authentication: User must be logged into Syntaq.Falcon
• Check permissions: User must have form creation/editing permissions

Save Button Not Working

• Check console: Look for JavaScript errors
• Check network: Ensure connection to Syntaq.Falcon
• Check form validity: Form must have valid structure

Messages Not Received

• Check event listener: Ensure message handler is properly set up
• Check origin: Verify origin validation isn't blocking messages
• Check console: Look for communication errors

API Reference

Endpoints

GET /Falcon/Forms/BuildCustom

Loads the custom form builder view.

Parameters:

• OriginalId (optional): Form ID to edit existing form
• Version (optional): Form version (defaults to "live")

Response: HTML page with form builder interface

POST /Falcon/Forms/SaveAndClose

Saves the form and returns completion status.

Request Body:

{
    "Form": {
        "Id": "guid",
        "OriginalId": "guid",
        "Version": 1,
        "Name": "Form Name",
        "Schema": "form-schema-json",
        // ... other form properties
    }
}

Response:

{
    "success": true,
    "message": {
        "type": "formSaved",
        "status": "success",
        "formId": "guid",
        "originalId": "guid",
        "version": 1,
        "timestamp": "2025-01-XX"
    }
}

Support

For technical support or questions about the Custom Form Builder View:

1. Check this documentation - Most common issues are covered here
2. Review browser console - Look for error messages
3. Contact your system administrator - For permission or configuration issues
4. Contact Syntaq.Falcon support - For platform-specific issues

Version History

• v1.0 (January 2025): Initial release with basic iframe integration
• Future versions will include enhanced features and improvements