TL;DR
We have support for conditional behaviors in@myndpm/dyn-forms
documented at mynd.dev and we are able to provide them easily like the Controls, Validators, AsyncValidators, etc.
In complex forms use-cases, some controls directly depend on the value or status of some other form control. Then we implement custom behaviors, like hiding
a field when another control has some value, or disabling
it depending on a complex condition, etc.
To support this, we've added Matchers
and Conditions
, which can be provided just like the Validators
and AsyncValidators
as we saw in the previous chapter of this series. If you want to get an initial idea from the code, you can check this source file and this real use-case demo.
DynTreeNode
Each dynamic control has a composed Node service instance which holds the data of this point in the form hierarchy. It provides the API and the data to manipulate the form in a customized way when needed.
The node has the control
Form Instance, the params
object, some utility methods to query
or select
parent and child controls, manipulate the visibility, etc. We will use this node inside the Conditions, Matchers and any other custom Handlers.
Conditions
To match a special requirement, we need to define one or more conditions, so when all (AND
) or one (OR
) of them are fulfilled we run a particular task. The Condition Function type consists of:
interface DynControlConditionFn {
(node: DynTreeNode): Observable<any>;
}
it streams a truthy value whenever the condition is fulfilled or not, for example, we could check if a specific control has the expected value:
(node: DynTreeNode) => {
return node.query('specific.control').valueChanges.pipe(
map(controlValue => controlValue === 'xValue'),
);
}
we can join these conditions with the required operator (AND | OR
) for our use-case, and then evaluate the action to execute in the specific Matcher
.
Matchers
We define our requirement with the Matchers that we want to run when
all or a single condition is satisfied:
match: [{
matchers: ['DISABLE'], // one or more matchers
when: [{
// the library provides a DEFAULT condition handler
// to process path, value and negation
path: 'other.field',
value: 'expectedValue'
}]
}]
the DISABLE
matcher is included in the library with ENABLE
, SHOW
, HIDE
(display: none) and INVISIBLE
(visibility: hidden).
One matcher consists of a function which performs a task in the form hierarchy; to do so, it receives the DynTreeNode
instance:
interface DynControlMatcherFn {
(args: {
node: DynTreeNode;
hasMatch: boolean;
firstTime: boolean;
results: any[];
}): void;
}
So, for example the DISABLE
matcher operates into the form control when the specified conditions are fulfilled (has match):
{
id: 'DISABLE',
fn: (): DynControlMatcherFn => {
return ({ node , hasMatch }) => {
hasMatch ? node.control.disable() : node.control.enable();
}
}
},
Advanced Stuff
This conditional processing enables us to do some additional logical operations, llike negate
the result of one or all the conditions, so we are able to play with conditions upside down and have the simplest specification of our requirements.
Matcher Example
For example, if we want to run a Matcher for all the options of a SELECT except a few of them, OR
without another condition, we can define that requirement with the few known values instead listing all the other values (which can be a long list), and negate the matcher input:
match: {
matchers: ['MyMatcherID'],
operator: 'OR', // the operator is AND by default
when: [
{
path: 'selectorName',
value: ['A', 'B', 'C'] // this will check if selectorName.value is IN this array
},
{
path: 'other.control',
value: 'anotherValue'
},
],
negate: true
}
the Matcher will receive hasMatch: true
when the selector has a value NOT in the provided list.
Also note that you can provide your Matcher factories with a custom id
like 'MyMatcherID'
just like we will do with conditions in the following section.
Condition Factory
We can register Factories with an id
and a fn
as we do with Validators, and parametrize them in the Config Object:
export interface DynControlCondition {
id: string;
fn: (...args: any[]) => DynControlConditionFn;
}
Remember that DynControlConditionFn
returns an Observable<boolean>
so you can implement and provide your custom conditions like:
const conditions = [{
id: 'MyConditionId',
fn: (...args: any[]) => { // Factory
return (node: DynTreeNode) => { // Condition
return node.control.valueChanges.pipe(map(...));
}
}
}];
@NgModule({
imports: [
DynFormsModule.forFeature({ conditions });
Conditions Config
You can use your custom conditions in these ways:
// inline function
when: [
(node: DynTreeNode) => {
// manipulate the form via DynTreeNode
}
]
// factory ID without arguments
when: [
'MyConditionId',
]
// parametrized factory
when: [
['MyConditionId', args],
]
// or declarative inline config
when: [
{
condition: 'MyConditionId',
path: 'other.control', // path is the only mandatory field in this format,
param1: 'anyValue', // the whole object will be passed to your DynControlConditionFn
},
]
in the last notation the whole config object is passed to the Factory, that's how the DEFAULT
condition handler receives the path
, value
and negate
config values.
Note: If no value
is configured, the DEFAULT
handler emits true
everytime the configured path
control value changes:
id: 'DEFAULT',
fn: ({ path, value, negate }): DynControlConditionFn => {
return (node: DynTreeNode): Observable<boolean> => {
if (value === undefined) {
return node.query(path).valueChanges.pipe(mapTo(true));
}
...
}
}
Conclusion
We have covered most of the details of Matchers
and Conditions
, and how one or many conditions can be configured so when one or all of them are fulfilled, they trigger a matcher which can modify the state of the form hierarchy via the DynTreeNode
API.
If you have an idea after this reading, or after using this library in an Angular App, please share it with us! :)
You can request features and join our discussions.
// PS. We are hiring!
Top comments (0)