Properties

Overview

Properties represent the form controls that will be in your Angular reactive form. When a FormGroup is created from a model settings instance, each property in the model setting will be generated as either a FormControl, FormGroup, or FormArray depending on how it is configured. Properties can be a simple type (e.g. string), complex type (e.g. a person with name and age), or an array. Each property will have a name, validity tests, and editability tests.

Details

⚡ View example ⚡

Most properties will be created by calling property() from ModelSettingsBuilder. This function takes as parameters the name of the property and an optional extension function. This extension function takes as a parameter the newly created property, which you can use to assign your property's tests and other settings. The property's name is strongly typed against the property names of the type for the model setting or parent property it belongs to.

If the property is a complex property (e.g. person object with name and age properties) you will assign its properties to an array of properties.

If a property is an array you will assign its arrayItemProperty to an instance of ArrayItemProperty<T>, which is created by calling arrayItemProperty() from ModelSettingsBuilder. This function is exactly the same as property() except that it does not take a property name as a parameter. This is because an array item does not have a name, but rather is just located at an index within the array it belongs to.

updateOn support

⚡ View example ⚡

Properties support Angular's updateOn functionality to allow for more fine grain control on which events cause a property's validation and/or editability tests to execute. Test execution can be delayed by setting a property's updateOn property from 'change' (default) to 'submit' or 'blur'.

Note: Tests will always run at least once when the form loads no matter what value is set for updateOn. For more details see this Angular GitHub issue

Value change subscription options

ℹ️ We encourage you to first learn about tests and rule sets before continuing on to this section.

⚡ View example ⚡

Sometimes when a property's test has an asynchronous rule you don't want it to execute immediatley after a value change. You may want to wait a certain amount of time between value changes (e.g. debounce) before the test is executed. You may also want to combine this with logic saying that if the value didn't change (e.g. the user typed something quickly and backspaced it out), then don't execute the test at all.

ng-form-rules allows for this fine grain control for each property. These options can be set via the property's valueChangeOptions, which allows for configuration at four different levels:

Level	Description
valueChangeOptions.self.asyncValid	Validation triggered by the property's own value change
valueChangeOptions.self.edit	Editability triggered by the property's own value change
valueChangeOptions.dependencyProperties.valid	Validation triggered by one of the property's dependency properties
valueChangeOptions.dependencyProperties.edit	Editability triggered by one of the property's dependency properties

For each of these levels two options can be configured:

1. debounceMilliseconds - Number of milliseconds to wait between value changes before executing tests.
2. distinctUntilChanged - Only execute tes tests if the value has changed. You would only really ever use this in conjunction with debounceMilliseconds.