# new NgxFormService(controls, formRegistry)
The NgxFormService provides utility methods for creating, managing, and validating Angular forms and form controls. It includes functionality for registering forms, adding controls, validating fields, and handling form data.
Service for managing Angular forms and form controls.
Parameters:
| Name | Type | Description |
|---|---|---|
controls |
WeakMap.<AbstractControl, FieldProperties>
|
A WeakMap to store control properties. |
formRegistry |
Map.<string, FormGroup>
|
A Map to store registered forms. |
Example
// Creating a form from components
const components = [
{ inputs: { name: 'username', type: 'text', required: true } },
{ inputs: { name: 'password', type: 'password', minLength: 8 } }
];
const form = NgxFormService.createFormFromComponents('loginForm', components, true);
// Validating fields
NgxFormService.validateFields(form);
// Getting form data
const formData = NgxFormService.getFormData(form);Methods
# static addControlFromProps(id, props, parentPropsopt) → {FormParent}
Creates and adds a form control to a form (existing or new) based on the provided component properties. Handles multi-page forms by managing FormArray structures and proper indexing. This method supports complex form scenarios including nested controls and page-based form organization. It automatically creates FormArrays for forms with multiple pages and manages page indexing.
Adds a control to a form based on component properties.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
id |
string
|
The unique identifier of the form |
|
props |
ComponentProperties
|
The properties of the component to create the control from |
|
parentProps |
props
|
<optional> |
Optional parent properties for context and configuration |
If page property is required but not provided or is invalid
Error
The form or created control (FormGroup or FormArray)
FormParent
# static addGroupToParent(parentForm, indexopt) → {FormArray}
Creates and adds a new FormGroup to the specified parent FormArray based on the component properties stored in the parent's metadata. This is used for dynamic form arrays where new groups need to be added at runtime. Clones the control at the specified index to maintain the same structure and validators.
Adds a new group to a parent FormArray.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
parentForm |
FormParent
|
The FormArray or FormGroup containing the parent FormArray |
|
index |
number
|
<optional> |
The index position to clone from; defaults to last index if length > 0, otherwise 0 |
The parent FormArray after adding the new group
FormArray
# static addRegistry(formId, formGroup) → {void}
Registers a FormGroup or FormArray with a unique identifier for global access throughout the application. This allows forms to be retrieved and managed centrally. Throws an error if the identifier is already in use to prevent conflicts.
Adds a form to the registry.
Parameters:
| Name | Type | Description |
|---|---|---|
formId |
string
|
The unique identifier for the form |
formGroup |
FormParent
|
The FormGroup or FormArray to be registered |
If a FormGroup with the given id is already registered
Error
void
# static cloneFormControl(control) → {AbstractControl}
Creates a deep copy of a FormControl, FormGroup, or FormArray, preserving validators but resetting values and state. This is useful for creating new instances of form controls with the same validation rules, particularly in dynamic FormArrays where new groups need to be added with identical structure.
Clones a form control with its validators.
Parameters:
| Name | Type | Description |
|---|---|---|
control |
AbstractControl
|
The control to clone (FormControl, FormGroup, or FormArray) |
If the control type is not supported
Error
A new instance of the control with the same validators
AbstractControl
# static createForm(id, formArrayopt, registryopt) → {FormGroup|FormArray}
Generates a FormGroup or FormArray based on the provided parameters. If formArray is true, creates a FormArray; otherwise creates a FormGroup. The form can optionally be registered in the global form registry for later access throughout the application. If a form with the given id already exists in the registry, it returns the existing form.
Creates a new form group or form array with the specified identifier.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
id |
string
|
Unique identifier for the form |
||
formArray |
boolean
|
<optional> |
false | Whether to create a FormArray instead of a FormGroup |
registry |
boolean
|
<optional> |
true | Whether to register the form in the global registry |
The created or existing form instance
FormGroup
|
FormArray
# static createFormFromChildren(id, registryopt, childrenopt) → {FormGroup}
Generates a FormGroup from an array of UIModelMetadata objects, extracting component properties and creating appropriate form controls. This method is specifically designed to work with the UI decorator system and provides automatic form generation from metadata.
Creates a form from UI model metadata children.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
id |
string
|
Unique identifier for the form |
||
registry |
boolean
|
<optional> |
false | Whether to register the created form in the global registry |
children |
Array.<UIModelMetadata>
|
<optional> |
Array of UI model metadata objects to create controls from |
The created FormGroup with controls for each child metadata
FormGroup
# static createFormFromComponents(id, components, registryopt) → {FormGroup}
Generates a FormGroup based on an array of component configurations and optionally registers it. This method processes component input configurations to create appropriate form controls with validation and initial values.
Creates a form from component configurations.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
id |
string
|
The unique identifier for the form |
||
components |
Array.<IComponentConfig>
|
An array of component configurations defining the form structure |
||
registry |
boolean
|
<optional> |
false | Whether to register the created form in the global registry |
The created FormGroup with controls for each component configuration
FormGroup
# static enableAllGroupControls(formGroup) → {void}
Recursively enables all form controls within the provided FormGroup or FormArray. This is useful for making all controls interactive after they have been disabled.
Enables all controls within a FormGroup or FormArray.
Parameters:
| Name | Type | Description |
|---|---|---|
formGroup |
FormArray
|
FormGroup
|
The FormGroup or FormArray to enable all controls for |
void
# static fromProps(props, updateModeopt) → {FormControl}
Generates a FormControl with validators and initial configuration based on the provided component properties. Handles different input types, sets initial values, and configures validation rules and update modes.
Creates a FormControl from component properties.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
props |
FieldProperties
|
The component properties defining the control configuration |
||
updateMode |
FieldUpdateMode
|
<optional> |
'change' | The update mode for the control ('change', 'blur', 'submit') |
The created FormControl with proper configuration and validators
FormControl
# static getComponentPropsFromGroupArray(formGroup, keyopt, groupArrayNameopt) → {Partial.<FieldProperties>}
Extracts component properties stored in the form group metadata. If a FormGroup is provided and groupArrayName is specified, it will look for the FormArray within the form structure.
Retrieves component properties from a FormGroup or FormArray.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
formGroup |
FormGroup
|
FormArray
|
The form group or form array to extract properties from |
|
key |
string
|
<optional> |
Optional key to retrieve a specific property |
groupArrayName |
string
|
<optional> |
Optional name of the group array if formGroup is not a FormArray |
The component properties or a specific property if key is provided
Partial.<FieldProperties>
# static getControlFromForm(formId, pathopt) → {AbstractControl}
Finds and returns an AbstractControl from a registered form using the form id and optional path. This method provides centralized access to form controls across the application by leveraging the form registry system.
Retrieves a control from a registered form.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
formId |
string
|
The unique identifier of the form in the registry |
|
path |
string
|
<optional> |
The optional dot-separated path to a specific control within the form |
If the form is not found in the registry or the control is not found in the form
Error
The requested AbstractControl (FormGroup, FormArray, or FormControl)
AbstractControl
# static getFormData(formGroup) → {Record.<string, unknown>}
Extracts and processes the data from a FormGroup, handling different input types and nested form groups. Performs type conversion for various HTML5 input types, validates nested controls, and manages multiple control scenarios. Automatically enables all group controls after data extraction.
Retrieves form data from a FormGroup.
Parameters:
| Name | Type | Description |
|---|---|---|
formGroup |
FormGroup
|
The FormGroup to extract data from |
An object containing the processed form data with proper type conversions
Record.<string, unknown>
# static getGroupFromParent(formGroup, parentName, indexopt) → {FormGroup}
Gets a FormGroup from the specified parent FormArray. If the group doesn't exist at the given index, it will create a new one using addGroupToParent.
Retrieves a FormGroup from a parent FormArray at the specified index.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
formGroup |
FormParent
|
The root form group containing the parent FormArray |
||
parentName |
string
|
The name of the parent FormArray to retrieve the group from |
||
index |
number
|
<optional> |
1 | The index of the group to retrieve |
The FormGroup at the specified index
FormGroup
# static getOnRegistry(idopt) → {FormParent|undefined}
Gets a FormGroup or FormArray from the registry using its unique identifier. Returns undefined if the form is not found in the registry. This method provides safe access to registered forms without throwing errors.
Retrieves a form from the registry by its identifier.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
id |
string
|
<optional> |
The unique identifier of the form to retrieve |
The FormGroup or FormArray if found, undefined otherwise
FormParent
|
undefined
# static getParentEl(el, tag) → {HTMLElement}
Traverses up the DOM tree to find the nearest parent element with the specified tag name. This is useful for finding container elements or specific parent components in the DOM hierarchy. The search is case-insensitive for tag name matching.
Finds a parent element with a specific tag in the DOM tree.
Parameters:
| Name | Type | Description |
|---|---|---|
el |
HTMLElement
|
The starting element to traverse from |
tag |
string
|
The tag name to search for (case-insensitive) |
If no parent with the specified tag is found in the DOM tree
Error
The found parent element with the specified tag
HTMLElement
# static getPropsFromControl(control) → {FieldProperties}
Gets the FieldProperties associated with a form control from the internal WeakMap. This method provides access to the original component properties that were used to create the control, enabling validation, rendering, and behavior configuration.
Retrieves properties from a FormControl, FormArray, or FormGroup.
Parameters:
| Name | Type | Description |
|---|---|---|
control |
FormControl
|
FormArray
|
FormGroup
|
The form control to get properties for |
The properties associated with the control, or empty object if not found
FieldProperties
# static isUniqueOnGroup(formGroup, operationopt, indexopt) → {boolean}
Validates that the primary key value in a FormGroup is unique among all groups in the parent FormArray. The uniqueness check behavior differs based on the operation type. For both CREATE and UPDATE operations, it checks that no other group in the array has the same primary key value.
Checks if a value is unique within a FormArray group.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
formGroup |
FormGroup
|
The FormGroup to check for uniqueness |
||
operation |
OperationKeys
|
<optional> |
OperationKeys.CREATE | The type of operation being performed |
index |
number
|
<optional> |
The index of the current group within the FormArray |
True if the value is unique, false otherwise
boolean
# static register(control, props) → {void}
Associates a form control with its component properties for later retrieval. This enables the service to maintain metadata about controls without creating memory leaks, as WeakMap automatically cleans up references when controls are garbage collected.
Registers a control with its properties in the internal WeakMap.
Parameters:
| Name | Type | Description |
|---|---|---|
control |
AbstractControl
|
The control to register (FormControl, FormGroup, or FormArray) |
props |
FieldProperties
|
The properties to associate with the control |
void
# static removeRegistry(formId) → {void}
Deletes a FormGroup or FormArray from the registry using its unique identifier. This cleans up the registry and allows the identifier to be reused. The form itself is not destroyed, only removed from the central registry.
Removes a form from the registry.
Parameters:
| Name | Type | Description |
|---|---|---|
formId |
string
|
The unique identifier of the form to be removed |
void
# static reset(formGroup) → {void}
Recursively resets all controls in a form group or a single form control, clearing values, errors, and marking them as pristine and untouched. For FormControls, it sets the value to empty string (except for checkbox types) and clears validation errors. For FormGroups, it recursively resets all child controls.
Resets a form group or form control.
Parameters:
| Name | Type | Description |
|---|---|---|
formGroup |
FormGroup
|
FormControl
|
The form group or form control to reset |
void
# static unregister(control) → {boolean}
Removes a control and its associated properties from the internal WeakMap. This cleans up the metadata tracking for the control and frees up memory. Returns true if the control was found and removed, false if it was not in the registry.
Unregisters a control from the internal WeakMap.
Parameters:
| Name | Type | Description |
|---|---|---|
control |
AbstractControl
|
The control to unregister (FormControl, FormGroup, or FormArray) |
True if the control was successfully unregistered, false otherwise
boolean
# static validateFields(control, pkopt, pathopt) → {boolean}
Recursively validates all fields in a form control or form group, marking them as touched and dirty. Performs comprehensive validation including uniqueness checks for primary keys in FormArray scenarios. This method ensures all validation rules are applied and form state is properly updated.
Validates fields in a form control or form group.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
control |
AbstractControl
|
The control or form group to validate |
|
pk |
string
|
<optional> |
Optional primary key field name for uniqueness validation |
path |
string
|
<optional> |
The path to the control within the form for error reporting |
If no control is found at the specified path or if the control type is unknown
Error
True if all fields are valid, false otherwise
boolean