{"_id":"56d91c5607ae190b0000446d","user":"54e3723b8ef7552300409bf4","version":{"_id":"56d91c5507ae190b00004460","__v":1,"project":"5515ba4981faf83900d2b10c","createdAt":"2016-03-04T05:25:41.052Z","releaseDate":"2016-03-04T05:25:41.052Z","categories":["56d91c5507ae190b00004464","56d91c5507ae190b00004465","56d91c5507ae190b00004466","56d91c5507ae190b00004467","56d91c5507ae190b00004468"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"8.0.0","version":"8.0.0"},"__v":0,"category":{"_id":"56d91c5507ae190b00004464","__v":1,"project":"5515ba4981faf83900d2b10c","pages":["56d91c5607ae190b00004469","56d91c5607ae190b0000446a","56d91c5607ae190b0000446b","56d91c5607ae190b0000446c","56d91c5607ae190b0000446d","56d91c5607ae190b0000446e","56d91c5607ae190b0000446f","56d91c5607ae190b00004470","56d91c5607ae190b00004471","56d91c5607ae190b00004472","56d91c5607ae190b00004473","56d91c5607ae190b00004474","56d91c5607ae190b00004475","56d91c5607ae190b00004476"],"version":"56d91c5507ae190b00004460","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-03-27T20:15:06.295Z","from_sync":false,"order":0,"slug":"guides","title":"Guides"},"project":"5515ba4981faf83900d2b10c","updates":["55a943604c661b3700cf4e40"],"next":{"pages":[],"description":""},"createdAt":"2015-03-28T18:28:07.233Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"There are four places where you can put expressions. The context in which these expressions are evaluated is important.\n\nThere are two different types of context and each is explained below:\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"expressionProperties, validators, & messages\"\n}\n[/block]\nThese 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).\n\nHere's an example of formlyExpressions using both strings and functions:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"vm.fields = [\\n  {\\n    type: 'input',\\n    key: 'bar',\\n    templateOptions: {required: true, label: 'IP Address'},\\n    expressionProperties: {\\n      'templateOptions.foo': '$modelValue', // set to the $modelValue of the control\\n      'templateOptions.required': 'model.foo === \\\"foobar\\\"'\\n    },\\n    hideExpression: function($viewValue, $modelValue, scope) {\\n      return scope.model.baz === 'foobar';\\n    }\\n    validators: {\\n      ipAddress: {\\n        expression: function($viewValue, $modelValue, scope) {\\n          var value = $modelValue || $viewValue;\\n          return /(\\\\d{1,3}\\\\.){3}\\\\d{1,3}/.test(value);\\n        },\\n        message: '$viewValue + \\\" is not a valid IP Address\\\"'\\n      },\\n      notLocalHost: '$viewValue !== \\\"127.0.0.1\\\"'\\n    },\\n    validation: {\\n      messages: {\\n        required: 'to.label + \\\" is required\\\"'\\n      }\\n    }\\n  }\\n];\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"hideExpression\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"A few notes\",\n  \"body\": \"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.\"\n}\n[/block]\nThis 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.\n\nIn 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`.\n\nIn string form, you have access to `options`, `index`, `formState`, and `formId` in addition to everything that's available on the `formly-form`'s scope.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"watcher\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Use expressionProperties\",\n  \"body\": \"It is recommended that you use `expressionProperties` (see below) if you can rather than `watcher`. This is because each `watcher` adds a `watcher` to angular's `$digest` cycle and therefore can slow down your application, but `expressionProperties` of fields share a single watcher (on the `model` and `formState`) and therefore will perform better. Also, if you're just trying to be notified when something changes, use `templateOptions.onChange` instead :-)\"\n}\n[/block]\nexpression 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// normal watcher\\n$scope.$watch(\\n  function expression(theScope) {},\\n  function listener(newValue, oldValue, theScope) {}\\n);\\n\\n// field watcher\\n$scope.$watch(\\n  function expression(field, theScope, stop) {},\\n  function listener(field, newValue, oldValue, theScope, stop) {}\\n);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]","excerpt":"Used throughout the library","slug":"formly-expressions","type":"basic","title":"Formly Expressions"}

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: [block:api-header] { "type": "basic", "title": "expressionProperties, validators, & messages" } [/block] 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: [block:code] { "codes": [ { "code": "vm.fields = [\n {\n type: 'input',\n key: 'bar',\n templateOptions: {required: true, label: 'IP Address'},\n expressionProperties: {\n 'templateOptions.foo': '$modelValue', // set to the $modelValue of the control\n 'templateOptions.required': 'model.foo === \"foobar\"'\n },\n hideExpression: function($viewValue, $modelValue, scope) {\n return scope.model.baz === 'foobar';\n }\n validators: {\n ipAddress: {\n expression: function($viewValue, $modelValue, scope) {\n var value = $modelValue || $viewValue;\n return /(\\d{1,3}\\.){3}\\d{1,3}/.test(value);\n },\n message: '$viewValue + \" is not a valid IP Address\"'\n },\n notLocalHost: '$viewValue !== \"127.0.0.1\"'\n },\n validation: {\n messages: {\n required: 'to.label + \" is required\"'\n }\n }\n }\n];", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "hideExpression" } [/block] [block:callout] { "type": "warning", "title": "A few notes", "body": "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." } [/block] 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. [block:api-header] { "type": "basic", "title": "watcher" } [/block] [block:callout] { "type": "warning", "title": "Use expressionProperties", "body": "It is recommended that you use `expressionProperties` (see below) if you can rather than `watcher`. This is because each `watcher` adds a `watcher` to angular's `$digest` cycle and therefore can slow down your application, but `expressionProperties` of fields share a single watcher (on the `model` and `formState`) and therefore will perform better. Also, if you're just trying to be notified when something changes, use `templateOptions.onChange` instead :-)" } [/block] 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: [block:code] { "codes": [ { "code": "// normal watcher\n$scope.$watch(\n function expression(theScope) {},\n function listener(newValue, oldValue, theScope) {}\n);\n\n// field watcher\n$scope.$watch(\n function expression(field, theScope, stop) {},\n function listener(field, newValue, oldValue, theScope, stop) {}\n);", "language": "javascript" } ] } [/block]