Forms

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.

Forms integration

Before you can start using Angular Forms integration as provided by the framework, ensure you register the BlueriqFormsModule in your AppModule:

import { NgModule } from '@angular/core';
import { BlueriqFormsModule } from '@blueriq/angular/forms';

@NgModule({
  // ...
  imports: [
    BlueriqFormsModule.forRoot(),
  ],
  // ...
})
export class AppModule {}

Creating Form Controls

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:

import { Component, Host, } from '@angular/core';
import { BlueriqComponent } from '@blueriq/angular';
import { BlueriqFormBuilder } from '@blueriq/angular/forms';
import { Field } from '@blueriq/core';

@Component({
  template: `<input type="text" [formControl]="formControl">`,
})
@BlueriqComponent({
  type: Field,
  selector: '[dataType=text]',
})
export class TextComponent {

  formControl = this.form.control(this.field);

  constructor(@Host() public field: Field, private form: BlueriqFormBuilder) {}

}

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.

Options

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:

• updateOn
  default: 'change'
  Specifies the update frequency of view updates to the form control instance, corresponding with Angular's equally named form control option. This affects the frequency of recomputing validation status, which is on each change by default. The '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.
• syncOn
  default: 'blur'
  Specifies the synchronization frequency of control value changes to the Blueriq 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'.
• disableWhen
  default: undefined
  Allows for providing a single presentation style or predicate function that determines whether or not the control is disabled or not. The control will always be disabled when Field.readonly is true, in which case this option is not considered.
• ifUnknown
  default: undefined
  Specifies a value that is to be set when the Runtime currently reports the field as having an unknown value. Useful for example with checkboxes that should be assigned a value of false upon being shown on a page.
• transformer
  default: undefined
  Specifies a transformer token to be used during the synchronization of values from Blueriq fields to and from Angular's form control instance. This type needs to be registered as Angular service, either from the component or from an Angular module.

Checkboxes

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.

<div *ngFor="let option of field.domain.options" class="checkbox">
  <label>
    <input type="checkbox" [bqCheckbox]="option.value" [name]="field.key"/> {{ option.displayValue }}
  </label>
</div>

To use bqCheckbox in feature modules, ensure that BlueriqFormsModule is imported.

Field Validation

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.

Value Transformers

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:

import { Injectable } from '@angular/core';
import { ValueTransformer, ValueTransformerContext } from '@blueriq/angular/forms';
import * as moment from 'moment';

@Injectable()
export class MomentTransformer implements ValueTransformer<Date, moment.Moment> {

  /** Translates a Javascript Date object to a Moment instance (if not null) */
  toControl(value: Date | null, context: ValueTransformerContext): moment.Moment | null {
    return value ? moment(value) : null;
  }

  /** Translates a Moment instance to a Javascript Date object (if not null) */
  toField(value: moment.Moment | null, context: ValueTransformerContext): Date | null {
    return value ? value.toDate() : null;
  }
}

This transformer service needs to be provided from an Angular module.