In a Blueriq frontend, one of the main activities is working with form inputs. The framework provides a toolkit for easy integration with Angular Forms that takes care of all aspects of handling user input.
Before you can start using Angular Forms integration as provided by the framework, ensure you register the BlueriqFormsModule
in your AppModule
:
With Angular Forms, all user input is represented by instances of FormControl
for which Angular Forms knows how to synchronize the value with HTML input elements such as text inputs, dropdowns, radios and checkboxes.
In typical Angular applications, you may use its FormBuilder
service to create form controls. For form controls that need to synchronize with a Blueriq Field
however, use BlueriqFormBuilder
instead. The FormControl
it creates will be configured to synchronize value and disabled state with a Field
and causes refresh fields to automatically trigger a refresh whenever their value changes.
The minimum example to get started is as follows:
You may use the function getBlueriqField
from @blueriq/angular/forms
to get access to the Blueriq Field
instance that is linked with an Angular FormControl
.
You can more specifically configure the created form control by passing additional options as second parameter to BlueriqFormBuilder.control
. The supported options are as follows:
'change'
'submit'
option is not supported given the dynamic nature of forms with Blueriq. To influence the moment when Blueriq field refreshes are triggered, use the syncOn
option instead.'blur'
Field
. This setting affects the moment when the FieldValueChangedAction
is dispatched, which in turn causes field refreshes to occur. When you specify 'update'
, the frequency is dependent on the update frequency as specified using the updateOn
option. The default is to synchronize values from Angular's form control to Blueriq's Field on 'blur'
, however since the blur event may not be triggered for all types of input such as checkboxes, in which case this property should be set to 'update'.undefined
Field.readonly
is true, in which case this option is not considered.undefined
false
upon being shown on a page.undefined
Nearly all form inputs can be handled using a single Angular FormControl
, however checkboxes are an exception. Each checkbox corresponds with a single option to toggle upon selecting and deselecting the checkbox. The framework provides the bqCheckbox
directive to automatically take care of synchronizing selection/deselection events to Blueriq fields.
To use
bqCheckbox
in feature modules, ensure thatBlueriqFormsModule
is imported.
Form controls are validated as a user types, based on the validation types of the associated field. To get access to the live validation messages of a form control, use the getFieldMessages
function from @blueriq/angular/forms
. These messages are equal to Field.messages
when the form control is not dirty (called pristine in Angular Forms) but will switch to the live validation messages once the user starts editing the value.
Whenever the page is updated by the Runtime, for example when a field is refreshed or a button is clicked, each form control will be marked pristine again to disregard the live validation messages and fallback to Blueriq's truth, in order to always prefer Blueriq messages unless a user has changed a field's value.
Only Blueriq's built-in validation types can be evaluated in the frontend, as more complex validation rules have to be evaluated by the Runtime.
By default, the value of a Blueriq field is synchronized to the form control one-to-one. If you need some sort of conversion between the value in Blueriq's Field
versus the value in Angular's FormControl
, you may specify a transformer when creating the form control through BlueriqFormBuilder
. As an example, this allows for conversion between Date
values in Blueriq fields and Moment
values for a date component that uses moment.js:
This transformer service needs to be provided from an Angular module.