Form Component - fgta5js Documentation

Overview

Inheritance Notice: Class Form inherits from the abstract base class Component.

The Form component scans a given HTML form for input elements that use the fgta5-component attribute (e.g. Textbox, Numberbox, Combobox, etc.) and instantiates corresponding component wrappers. It provides APIs to lock/unlock all inputs at once, load data, retrieve modified data, handle file uploads, and validate all inputs with unified error feedback.

HTML Markup

Define your form element and assign a unique ID. Decorate it with attributes like primarykey, locked, and autoid, and style input containers using standard fields.

<form id="myform" primarykey="obj_id" locked="true" autoid="true">
  <div class="input-field" field="obj_id">
    <label for="obj_id">ID</label>
    <input id="obj_id" fgta5-component="Textbox" binding="id" disabled>
  </div>

  <div class="input-field" field="obj_name">
    <label for="obj_name">Name</label>
    <input id="obj_name" fgta5-component="Textbox" binding="name" required>
  </div>
</form>

Initialize and render the form in Javascript:

import Form from './src/components/Form.mjs';

const form = new Form('myform');
form.render();

// Unlock form to start editing
form.lock(false);

HTML Attributes

Attribute	Values	Description
`primarykey`	`String`	Designates the ID of the input element that serves as the form's primary key identifier.
`locked`	`"true" \| "false"`	Sets the initial edit/view lock state. When true, all component interactions are disabled.
`autoid`	`"true" \| "false"`	Configures whether ID values are expected to be auto-generated.

Properties

Property	Type	Description
`Inputs`	`Object`	An object mapping element IDs to their respective component wrapper instances (e.g. `Textbox`, `Checkbox`, etc.).
`AutoID`	`Boolean`	(Read-only) Returns `true` if the form attribute `autoid` is configured to generate IDs automatically.
`PrimaryKey`	`String`	(Read-only) Returns the element ID representing the primary key of this form.

Methods

Method	Arguments	Description
`constructor(id)`	`(id: String)`	Constructs the form, registers elements with `fgta5-component` into the `Inputs` registry, and reads configuration attributes.
`render()`	`()`	Binds each child input to the form and initializes the initial form locking state. Should be called after instantiation.
`lock(lock)`	`(lock: Boolean)`	Locks (`true`) or unlocks (`false`) all input components inside the form. Dispatches appropriate custom events.
`isLocked()`	`()`	Returns `true` if the form is currently locked (read-only mode).
`isNew()`	`()`	Returns `true` if the form holds data marked as unsaved or new.
`setAsNewData()`	`()`	Forcefully sets the form state to indicate it contains new/unsaved data.
`reset()`	`()`	Resets the value of all input components back to their last committed state and marks the form as not new.
`clear(text)`	`(text: String = '')`	Clears the raw value of all input elements in the form to the specified string.
`acceptChanges()`	`()`	Commits the current values of all input fields as the new baseline/saved state, and marks the form as not new.
`isChanged()`	`()`	Checks whether any registered input field has a value differing from its last committed baseline.
`getLastError()`	`()`	Returns the last validation error message string, or `null`/`undefined`.
`getPrimaryInput()`	`()`	Returns the input component instance that corresponds to the designated `PrimaryKey`.
`setData(data)`	`(data: Object)`	Populates all registered inputs with values from the given data object (matching by binding names) and calls `acceptChanges()`.
`newData(data)`	`(data: Object = {})`	Unlocks the form, marks the form as new, and initializes inputs with fields from the provided data object.
`getData()`	`()`	Extracts and returns the current form state as a plain object mapping bindings to values.
`getOriginalData()`	`()`	Returns the original object structure that was loaded via the most recent call to `setData()`.
`getDataChanged()`	`()`	Returns a plain object containing only the fields that have been modified. The primary key field is always included.
`getFiles()`	`()`	Returns an object containing files from modified `Filebox` components, or `null` if none are changed.
`validate()`	`()`	Validates every input component in the form sequentially. Returns `true` if all inputs are valid, or `false` (and stores the first error).
`acceptInput()`	`()`	Temporarily blurs and refocuses the active element to ensure in-progress keystrokes are properly recorded in the model.
`addEventListener(event, callback)`	`(event: String, callback: Function)`	Attaches an event handler to the underlying native form element.

Custom Events

The form component fires custom DOM events on the native <form> element that you can listen to:

Event Name	Description
`locked`	Dispatched when the form is successfully locked (read-only mode enabled).
`unlocked`	Dispatched when the form is successfully unlocked (edit mode enabled).