Vocphone JavaScript Library

Lightweight form rendering and submission helper for VocPhone projects. This library renders JSON-driven forms into the DOM, collects values (FormData or plain objects), and supports auto-submit to an API endpoint.

Documentation

• Full API & Field Reference →
  • renderForm
  • Field Types — text, select, radio, checkbox, boolean, file, avatar, tags, timezone, users, audio_select, table, field-select, row, group
  • Default Values
  • Validation
  • Bootstrap Integration
  • Value Extraction
  • Form Submission
  • CSS Class Reference
  • TypeScript Types

Quick Start

Install dependencies and build (if developing locally):

npm install
npm run build

Include the bundle from a CDN (UMD/global) or import as a module in your app.

CDN Usage

Global UMD bundle:

<div id="render-form"></div>
<script src="https://cdn.jsdelivr.net/npm/voc-lib-js@latest/dist/main.global.js"></script>
<script>
    const rendered = VocLibJs.FormsLib.renderForm('#render-form', formSchema);
    rendered.onSubmit((data) => {
        console.log([...data.entries()]);
    });
</script>

ES Module:

<div id="render-form"></div>
<script type="module">
    import { FormsLib } from 'https://cdn.jsdelivr.net/npm/voc-lib-js@latest/dist/main.mjs';
    const rendered = FormsLib.renderForm('#render-form', formSchema);
    console.log(rendered.getValues(false)); // plain object
</script>

NPM / Framework Usage

npm install voc-lib-js

<script setup>
import { onMounted, ref } from 'vue';
import { FormsLib } from 'voc-lib-js';

const formRef = ref(null);

onMounted(() => {
    formRef.value = FormsLib.renderForm('#render-form', formSchema);
});
</script>

<template>
    <div id="render-form"></div>
</template>

Works the same in React, Angular, Svelte, or vanilla JS.

Example Form Schema

{
    "id": "user-registration",
    "code": "reg_001",
    "form_name": "User Registration",
    "default_values": {
        "country": "usa"
    },
    "submit_config": {
        "url": "https://api.example.com/forms/submit",
        "api_token": "<token>"
    },
    "fields": [
        {
            "type": "row",
            "items": [
                { "label": "First Name", "key": "first_name", "type": "text", "required": true },
                { "label": "Last Name",  "key": "last_name",  "type": "text", "required": true }
            ]
        },
        { "label": "Email",    "key": "email",    "type": "email",    "required": true },
        { "label": "Password", "key": "password", "type": "password", "required": true },
        {
            "label": "Country", "key": "country", "type": "select",
            "options": [
                { "label": "United States", "value": "usa" },
                { "label": "Canada",        "value": "canada" }
            ]
        },
        {
            "label": "Notification Emails",
            "key": "notify_emails",
            "type": "tags",
            "tag_types": ["email"],
            "hint_text": "Press <b>Enter</b> or <b>,</b> after each address."
        }
    ]
}

Reading Values & Submission

const rendered = FormsLib.renderForm('#render-form', formSchema);

// FormData (default — ideal for file uploads)
const data = rendered.getValues();
console.log(data.get('email'));

// Plain object
const obj = rendered.getValues(false);
console.log(obj);

// Manual submit handler
rendered.onSubmit((data, event) => {
    fetch('/api/submit', { method: 'POST', body: data });
});

// Auto-submit: provide submit_config in the schema or options —
// the library posts automatically and calls onSubmitResult with (response, error)

For the full API including all field types, validation options, Bootstrap integration, and CSS class reference see docs/forms-lib.md.

Contributing

1. Fork the repo and create a feature branch.
2. Run npm install and npm run build to test locally.
3. Open test pages from tests-local/vanilla/forms-lib/ in a browser to manually verify field behaviour.
4. Open a PR with a clear description.

License

MIT