# FormRenderer.js Overview

`FrontEnd/JsLibs2/core/FormRenderer.js` provides a lightweight helper for building HTML forms from JSON metadata. It relies on jQuery for DOM manipulation and uses the shared `FormUtils` and `Toast` utilities.

## Features

- Generate form inputs for **text**, **select**, **checkbox** and **radio** fields.
- Optional validation hooks per field and for the entire form.
- Simple callback on submission with serialized form data.
- Bootstrap friendly markup so forms look consistent with the rest of the UI.

## Basic Usage

```javascript
import { FormRenderer } from '../JsLibs2/core/FormRenderer.js';

const renderer = new FormRenderer('#formArea', {
    fields: [
        { name: 'first_name', label: 'First Name', type: 'text',
          validate: v => v ? true : 'First name required' },
        { name: 'role', type: 'select', options: [
            { value: 'admin', label: 'Admin' },
            { value: 'user', label: 'User' }
        ] },
        { name: 'subscribe', type: 'checkbox', label: 'Subscribe?' }
    ]
}, {
    onSubmit: data => console.log('submit', data)
});
```

`onSubmit` receives the object returned by `FormUtils.serializeForm`. If any validation function returns a string, the message is shown through `Toast` and submission is aborted.

If no `buttons` array is supplied in the metadata, a single submit button is automatically rendered. The text for this button is taken from the `submitText` option.

### Conditional Fields

Fields may define `condition_field` and `condition_value` properties. When present the element is wrapped in a hidden container and shown only when the controlling input's value matches. `FormRenderer` calls `FormUtils.initConditionalFields` so any form rendered with this helper automatically toggles conditional inputs.

## API

```
new FormRenderer(container, metadata, options)
```

- **container** – CSS selector or element where the form will be rendered.
- **metadata.fields** – Array describing fields (name, label, type, options?, validate?).
- **options.onSubmit(data, $form)** – Callback executed when the form is valid and submitted.
- **options.validate(data)** – Optional global validation function.
- **options.initialData** – Object of default values.
- **metadata.buttons** – Optional array of button definitions. Each button
  should provide a `label`, `action_type` and optional `action_payload`.
  If omitted, a single submit button is added automatically.
- **options.submitText** – Text for the auto-generated submit button
  (default "Submit").

Use `destroy()` to remove the form and unbind events when done.