turboforms-embed-sdk

v1.0.5

Published

7 days ago

Reusable vanilla JS form library that works with React, Angular, Ionic, etc.

Downloads

312

0High
0Medium
0Low

srinidhirao

form vanilla-js library iframe react angular ionic

Unvired Forms SDK

A powerful, lightweight JavaScript SDK for rendering dynamic forms with advanced features like geolocation, camera integration, barcode scanning, and file uploads. Built on Form.io JSON schema, this SDK works seamlessly across all modern web frameworks and mobile platforms.

🌟 Features

Universal Compatibility: Works with React.js, Angular, Ionic, Cordova, and vanilla JavaScript
Advanced Components: Built-in support for geolocation, camera, barcode scanning, and file attachments
Form.io Integration: Renders Form.io JSON schema-based forms with full feature support
Cross-Platform: Seamless integration across web and mobile applications
Event-Driven: Robust event callback system for form interactions
TypeScript Support: Full TypeScript definitions included

📦 Installation

npm install unvired-forms-sdk

🚀 Usage Examples

Vanilla JavaScript

<!DOCTYPE html>
<html>
<head>
    <title>Unvired Forms Integration</title>
</head>
<body>
    <div id="form-container"></div>
    
    <script type="module">
        import { loadUnviredForms } from './dist/unvired-forms-sdk.js';
        
        const formInstance = loadUnviredForms({
            formsData: formTemplateData,
            submissionData: preFillData || {},
            eventCallback: function (event) {
                console.log('Form event:', event);
                
                switch (event.type) {
                    case 'FORM_SUBMIT':
                        console.log('Form submitted:', event.data);
                        break;
                    case 'FORM_BACK_NAVIGATION':
                        window.history.back();
                        break;
                }
            },
            container: document.getElementById('form-container'),
            options: {
                formioLibPath: {
                    formioPath: "./dist/assets/formio.full.min.js",
                    lessFilesPath: "./dist/assets/fomantic-ui/definitions"
                },
                mode: "render",
                platform: "web",
                showBackButton: true,
                userData: {
                    user: "John Doe",
                    email: "[email protected]"
                }
            }
        });
    </script>
</body>
</html>

React.js Integration

import React, { useRef, useEffect } from 'react';
import { loadUnviredForms } from 'unvired-forms-sdk';

const UnviredForm = ({ formData, onSubmit, onBack }) => {
    const containerRef = useRef(null);
    const formInstanceRef = useRef(null);
    
    useEffect(() => {
        if (containerRef.current && formData) {
            formInstanceRef.current = loadUnviredForms({
                formsData: formData,
                submissionData: {},
                eventCallback: (event) => {
                    switch (event.type) {
                        case 'FORM_SUBMIT':
                            onSubmit?.(event.data);
                            break;
                        case 'FORM_BACK_NAVIGATION':
                            onBack?.();
                            break;
                    }
                },
                container: containerRef.current,
                options: {
                    formioLibPath: {
                        formioPath: "./assets/formio.full.min.js",
                        lessFilesPath: "./assets/fomantic-ui/definitions"
                    },
                    mode: "render",
                    platform: "web",
                    showBackButton: true
                }
            });
        }
        
        return () => {
            // Cleanup if needed
        };
    }, [formData, onSubmit, onBack]);
    
    return <div ref={containerRef} style={{ width: '100%', height: '100%' }} />;
};

export default UnviredForm;

Angular Integration

import { Component, ElementRef, ViewChild, Input, Output, EventEmitter } from '@angular/core';
import { loadUnviredForms, FormEvent } from 'unvired-forms-sdk';

@Component({
  selector: 'app-unvired-form',
  template: '<div #formContainer style="width: 100%; height: 100%;"></div>'
})
export class UnviredFormComponent {
  @ViewChild('formContainer', { static: true }) formContainer!: ElementRef;
  @Input() formData: any;
  @Output() formSubmit = new EventEmitter<any>();
  @Output() formBack = new EventEmitter<void>();
  
  ngOnInit() {
    if (this.formData) {
      loadUnviredForms({
        formsData: this.formData,
        submissionData: {},
        eventCallback: (event: FormEvent) => {
          switch (event.type) {
            case 'FORM_SUBMIT':
              this.formSubmit.emit(event.data);
              break;
            case 'FORM_BACK_NAVIGATION':
              this.formBack.emit();
              break;
          }
        },
        container: this.formContainer.nativeElement,
        options: {
          formioLibPath: {
            formioPath: "./assets/formio.full.min.js",
            lessFilesPath: "./assets/fomantic-ui/definitions"
          },
          mode: "render",
          platform: "web"
        }
      });
    }
  }
}

Cordova Integration

// In your Cordova app's main JavaScript file
document.addEventListener('deviceready', function() {
    import('./js/unvired-forms-sdk.js').then(({ loadUnviredForms }) => {
        const formInstance = loadUnviredForms({
            formsData: formTemplateData,
            submissionData: {},
            eventCallback: function (event) {
                switch (event.type) {
                    case 'FORM_SUBMIT':
                        console.log('Form submitted:', event.data);
                        break;
                    case 'OPEN_CAMERA':
                        handleCameraRequest(event.data);
                        break;
                    case 'LOCATION_REQUEST':
                        handleLocationRequest(event.data);
                        break;
                }
            },
            container: document.getElementById('form-container'),
            options: {
                formioLibPath: {
                    formioPath: "./js/formio.full.min.js",
                    lessFilesPath: "./css/fomantic-ui/definitions"
                },
                mode: "render",
                platform: "cordova",
                showBackButton: true
            }
        });
    });
}, false);

📋 API Reference

LoadUnviredFormsParams

| Property | Type | Required | Description | |----------|------|----------|-------------| | formsData | string | object | ✅ | Form.io JSON schema or JSON string | | submissionData | object | ❌ | Pre-filled form data | | eventCallback | function | ❌ | Event handler function | | container | HTMLElement | ❌ | DOM container element | | options | object | ❌ | Configuration options |

Options Configuration

| Property | Type | Description | |----------|------|-------------| | formioLibPath | object | FormIO library paths configuration | | nestedFormData | array | Nested form data | | masterData | array | Master data for dropdowns | | title | string | Form title | | description | string | Form description | | mode | string | Form mode: 'render', 'readOnly', 'print', 'pdf' | | platform | string | Platform: 'web', 'android', 'ios', 'cordova' | | language | string | Language code | | translations | object | Translation strings | | themeData | object | Custom theme configuration | | showBackButton | boolean | Show/hide back navigation | | showMoreButton | boolean | Show/hide more options menu | | userData | object | User context data | | appData | object | Application data | | environmentVariable | array | Environment variables |

Event Types

| Event | Description | |-------|-------------| | FORM_RENDER | Form rendered successfully | | FORM_SUBMIT | Form submission completed | | FORM_SAVE | Form data saved | | FORM_BACK_NAVIGATION | Back button pressed | | FORM_ONCHANGE | Form field value changed | | OPEN_CAMERA | Camera access requested | | LOCATION_REQUEST | Location access requested | | BARCODE_SCAN | Barcode scanning completed | | GET_ATTACHMENT | Attachment request | | ERROR | Error occurred |

🔧 Form Instance Methods

The loadUnviredForms function returns a FormInstance object with the following methods:

const formInstance = loadUnviredForms(params);

// Send actions to the form
formInstance.sendAction({
    type: "SET_IMAGE_DATA",
    imageData: base64ImageData,
    controlId: "photo_field"
});

// Get attachments (if available)
if (formInstance.getAttachments) {
    const attachments = await formInstance.getAttachments();
    console.log('Form attachments:', attachments);
}

// Clear attachments (if available)
if (formInstance.clearAttachments) {
    const success = await formInstance.clearAttachments();
    console.log('Attachments cleared:', success);
}

// Validate attachments (if available)
if (formInstance.validateAttachments) {
    formInstance.validateAttachments(formData);
}

// Delete specific attachment (if available)
if (formInstance.deleteAttachment) {
    const success = await formInstance.deleteAttachment('fileId');
    console.log('Attachment deleted:', success);
}

Action Types

// Set image data for camera controls
formInstance.sendAction({
    type: "SET_IMAGE_DATA",
    imageData: "data:image/jpeg;base64,...",
    controlId: "camera_field_id"
});

// Set barcode scan result
formInstance.sendAction({
    type: "SET_BARCODE_DATA",
    scannedValue: "123456789",
    controlId: "barcode_field_id"
});

// Set location data
formInstance.sendAction({
    type: "SET_LOCATION_DATA",
    location: "40.7128,-74.0060",
    coordinates: { lat: 40.7128, lng: -74.0060 },
    controlId: "location_field_id"
});

🛠 Error Handling

The SDK provides comprehensive error handling with specific error codes:

loadUnviredForms({
    // ... other params
    eventCallback: function(event) {
        if (event.type === 'ERROR') {
            switch (event.errorMessage) {
                case 'Error Code 001 contact your admin':
                    console.error('Invalid formsData JSON');
                    break;
                case 'Error Code 004 contact your admin':
                    console.error('User Data not Provided');
                    break;
                case 'Error Code 013 contact your admin or tech team':
                    console.error('Attachments missing from storage');
                    break;
                // Handle other error codes...
            }
        }
    }
});

Error Codes Reference

| Code | Description | |------|-------------| | 001 | Invalid formsData JSON | | 002 | Nested form validation error | | 003 | Master data validation error | | 004 | User Data not Provided | | 005 | Form render error | | 006 | Form submit error | | 007 | Form complete error | | 008 | Location permission denied | | 009 | Location unavailable | | 010 | Location request timeout | | 011 | Location unknown error | | 012 | Camera access error | | 013 | Attachments missing from storage | | 014 | Failed to validate attachments | | 015 | File not found in IndexedDB |

🔐 Security Considerations

Validate all form data before processing
Implement proper file upload restrictions
Use HTTPS in production environments
Sanitize user inputs to prevent XSS attacks

🛠 Build Process

Development Setup

Install dependencies
```
npm install
```
Build for web platforms
```
npm run build
```
Build for Flutter (optional)
```
npm run build:flutter
```

Build Scripts

npm run build - Executes node scripts/build.js for standard web build
npm run build:flutter - Executes node scripts/build-flutter.js for Flutter-specific build

Build Output

The build process generates:

dist/unvired-forms-sdk.js - Main SDK bundle
dist/index.d.ts - TypeScript definitions
dist/assets/ - FormIO library and UI assets

🧪 Platform Compatibility

| Platform | Version | Status | |----------|---------|--------| | React.js | 16.8+ | ✅ Fully Supported | | Angular | 12+ | ✅ Fully Supported | | Vue.js | 3.0+ | ✅ Fully Supported | | Ionic | 5+ | ✅ Fully Supported | | Cordova | 9+ | ✅ Fully Supported | | Vanilla JS | ES6+ | ✅ Fully Supported |

📝 License

MIT - See LICENSE file for details.