Formly Expressions
Used throughout the library
There are four places where you can put expressions. The context in which these expressions are evaluated is important.
There are two different types of context and each is explained below:
expressionProperties, validators, & messages
These expressions can be functions or expression strings. If it's a function, it's invoked with the arguments $viewValue
, $modelValue
, and scope
. The scope in this case, is the field's scope. If it's an expression string, it is evaluated using $scope.$eval
with a locals object that has $viewValue
and $modelValue
(however, in the case of expressionProperties
, $viewValue
will simply be the $modelValue
because ok into the ngModelController
but we want to keep the api consistent).
Here's an example of formlyExpressions using both strings and functions:
vm.fields = [
{
type: 'input',
key: 'bar',
templateOptions: {required: true, label: 'IP Address'},
expressionProperties: {
'templateOptions.foo': '$modelValue', // set to the $modelValue of the control
'templateOptions.required': 'model.foo === "foobar"'
},
hideExpression: function($viewValue, $modelValue, scope) {
return scope.model.baz === 'foobar';
}
validators: {
ipAddress: {
expression: function($viewValue, $modelValue, scope) {
var value = $modelValue || $viewValue;
return /(\d{1,3}\.){3}\d{1,3}/.test(value);
},
message: '$viewValue + " is not a valid IP Address"'
},
notLocalHost: '$viewValue !== "127.0.0.1"'
},
validation: {
messages: {
required: 'to.label + " is required"'
}
}
}
];
hideExpression
A few notes
These are evaluated in a similar way (but not the same way) as
expressionProperties
. Make sure to read the docs below to see how it differs. Also, this doesn't accept promises, you can only do synchronous operations here.
This is almost the same as expressionProperties
with a slight difference. It's run in the context of the form
rather than the field
. The reason for this is if the field is hidden to start, then it's not yet been compiled and therefore doesn't actually have a scope yet. Formly tries to combat this by simulating the field's context. So most of the time you should experience the same behavior.
In the function form, you still get passed the $viewValue
, $modelValue
, and scope
. However, the scope
in this case is the formly-form
scope (not the formly-field
) and the $modelValue
and $viewValue
are actually both just the $modelValue
.
In string form, you have access to options
, index
, formState
, and formId
in addition to everything that's available on the formly-form
's scope.
watcher
Use expressionProperties
It is recommended that you use
expressionProperties
(see below) if you can rather thanwatcher
. This is because eachwatcher
adds awatcher
to angular's$digest
cycle and therefore can slow down your application, butexpressionProperties
of fields share a single watcher (on themodel
andformState
) and therefore will perform better. Also, if you're just trying to be notified when something changes, usetemplateOptions.onChange
instead :-)
expression and listener can be functions or expression strings. This is a regular angular $watch
(depending on the specified type
) function and it is created on the formly-form
scope, despite being applied to a specific field. This allows the expressions to run even if the field's scope has been destroyed (via an ng-if like when the field is hidden). The function signature differs from a normal $watch
however:
// normal watcher
$scope.$watch(
function expression(theScope) {},
function listener(newValue, oldValue, theScope) {}
);
// field watcher
$scope.$watch(
function expression(field, theScope, stop) {},
function listener(field, newValue, oldValue, theScope, stop) {}
);
Updated less than a minute ago