feat(core): rename expressionProperties to expressions

fix #2853

UPGRADE-6.0.md

@@ -184,7 +184,11 @@ UPGRADE FROM 5.0 to 6.0
 @ngx-formly/core/json-schema
 ----------------------------
 
-- In case you use the extra option `map` to customize the generated `fieldArray`, you need to make change to take account of `fieldArray` which return `function` instead of an object.
+- In case you use the extra option `map` to customize the generated field, you need to make change to take account of following properties:
+  1. `fieldArray` which return `function` instead of an object.
+  2. `templateOptions` which has been replaced by `props`.
+  3. `hideExpression` which has been replaced by `expressions: { hide: ... }`.
+  4. `expressionProperties` which has been replaced by `expressions`.
 
 ```ts
 this.formlyJsonschema.toFieldConfig(schema, {

demo/src/app/examples/advanced/i18n-alternative/translate.extension.ts

@@ -10,8 +10,8 @@ export class TranslateExtension implements FormlyExtension {
     }
 
     props._translated = true;
-    field.expressionProperties = {
-      ...(field.expressionProperties || {}),
+    field.expressions = {
+      ...(field.expressions || {}),
       'props.label': this.translate.stream(props.label),
     };
   }

demo/src/app/examples/advanced/i18n/app.component.ts

@@ -23,15 +23,15 @@ export class AppComponent {
           { label: 'en', value: 'en' },
         ],
       },
-      expressionProperties: {
+      expressions: {
         'props.label': this.translate.stream('FORM.LANG'),
       },
     },
     {
       key: 'name',
       type: 'input',
       props: { required: true },
-      expressionProperties: {
+      expressions: {
         'props.label': this.translate.stream('FORM.NAME'),
       },
     },

demo/src/app/examples/advanced/i18n/config.module.ts

@@ -19,9 +19,9 @@ import { AppComponent } from './app.component';
               description: `
               This is an example of using ngx-formly with ngx-translate to internationalize your forms.
               <div>
-                This example demonstrates dynamic i18n using <code>expressionProperties</code>.
+                This example demonstrates dynamic i18n using <code>expressions</code>.
                 If you don't need a dynamic solution (language doesn't change after the app has started up,
-                simply omit the <code>expressionProperties</code> in the example.
+                simply omit the <code>expressions</code> in the example.
               </div>
             `,
               component: AppComponent,

demo/src/app/examples/bootstrap-specific/advanced-layout/app.component.ts

@@ -30,7 +30,7 @@ export class AppComponent {
           props: {
             label: 'Last Name',
           },
-          expressionProperties: {
+          expressions: {
             'props.disabled': '!model.firstName',
           },
         },

demo/src/app/examples/field-options/expression-properties/app.component.ts

@@ -25,7 +25,7 @@ export class AppComponent {
         label: 'Hey!',
         placeholder: 'This one is disabled if there is no text in the other input',
       },
-      expressionProperties: {
+      expressions: {
         'props.disabled': '!model.text',
       },
     },

demo/src/app/examples/field-options/hide-fields/app.component.ts

@@ -26,7 +26,9 @@ export class AppComponent {
       props: {
         label: 'I like twix',
       },
-      hideExpression: '!model.name',
+      expressions: {
+        hide: '!model.name',
+      },
     },
   ];
 

demo/src/app/examples/field-options/hide-fields/config.module.ts

@@ -17,8 +17,8 @@ import { AppComponent } from './app.component';
             {
               title: 'Hide Fields',
               description: `
-              <code>hideExpression</code> is used to set the
-              <code>hide</code> property of your field.
+              <code>expressions</code> is used to set the
+              <code>hide</code> property of your field conditionally based on model value.
             `,
               component: AppComponent,
               files: [

demo/src/app/examples/form-options/form-state/app.component.ts

@@ -22,7 +22,7 @@ export class AppComponent {
       props: {
         label: 'First Name',
       },
-      expressionProperties: {
+      expressions: {
         // apply expressionProperty for disabled based on formState
         'props.disabled': 'formState.disabled',
       },

demo/src/app/examples/introduction/app.component.ts

@@ -32,9 +32,9 @@ export class AppComponent {
         placeholder: 'It allows you to build and maintain your forms with the ease of JavaScript :-)',
         description: '',
       },
-      expressionProperties: {
+      expressions: {
         focus: 'formState.awesomeIsForced',
-        'props.description': (model, formState) => {
+        'props.description': ({ options: { formState } }) => {
           if (formState.awesomeIsForced) {
             return 'And look! This field magically got focus!';
           }
@@ -47,9 +47,9 @@ export class AppComponent {
       key: 'awesome',
       type: 'checkbox',
       props: { label: '' },
-      expressionProperties: {
+      expressions: {
         'props.disabled': 'formState.awesomeIsForced',
-        'props.label': (model, formState) => {
+        'props.label': ({ options: { formState } }) => {
           if (formState.awesomeIsForced) {
             return 'Too bad, formly is really awesome...';
           } else {
@@ -61,8 +61,13 @@ export class AppComponent {
     {
       key: 'whyNot',
       type: 'textarea',
-      expressionProperties: {
-        'props.placeholder': (model, formState) => {
+      props: {
+        label: 'Why Not?',
+        placeholder: 'Type in here... I dare you',
+      },
+      expressions: {
+        hide: 'model.awesome',
+        'props.placeholder': ({ options: { formState } }) => {
           if (formState.awesomeIsForced) {
             return `Too bad... It really is awesome! Wasn't that cool?`;
           } else {
@@ -71,11 +76,6 @@ export class AppComponent {
         },
         'props.disabled': 'formState.awesomeIsForced',
       },
-      hideExpression: 'model.awesome',
-      props: {
-        label: 'Why Not?',
-        placeholder: 'Type in here... I dare you',
-      },
     },
     {
       key: 'custom',

demo/src/app/examples/other/advanced-layout-flex/app.component.ts

@@ -32,7 +32,7 @@ export class AppComponent {
           props: {
             label: 'Last Name',
           },
-          expressionProperties: {
+          expressions: {
             'props.disabled': '!model.firstName',
           },
         },

demo/src/app/examples/other/cascaded-select-json/app.component.ts

@@ -55,7 +55,7 @@ export class AppComponent {
         valueProp: 'id',
         labelProp: 'name',
       },
-      expressionProperties: {
+      expressions: {
         'props.options': 'formState.selectOptionsData.teams.filter(team => team.sportId === model.sport)',
         // reset model when updating select options
         'model.team': `field.props.options.find(o => o.id === model.team) ? model.team:null`,
@@ -70,7 +70,7 @@ export class AppComponent {
         valueProp: 'id',
         labelProp: 'name',
       },
-      expressionProperties: {
+      expressions: {
         'props.options': 'formState.selectOptionsData.players.filter(player => player.teamId === model.team)',
         // reset model when updating select options
         'model.player': `field.props.options.find(o => o.id === model.player) ? model.player:null`,

demo/src/app/examples/other/hide-fields-with-animations/app.component.ts

@@ -31,10 +31,12 @@ export class AppComponent {
     {
       key: 'lastname',
       type: 'input',
-      hideExpression: (model) => !model.firstName,
       props: {
         label: 'Last name',
       },
+      expressions: {
+        hide: ({ model }) => !model.firstName,
+      },
     },
   ];
 

demo/src/app/examples/other/json-powered/config.module.ts

@@ -19,7 +19,7 @@ import { AppComponent } from './app.component';
               description: `
               This is an example of powering a form strictly by JSON. The common use case for this
               would be to persist the form configuration in the database and then send the configuration
-              up to power the form. Notice that you can still use most features like <code>expressionProperties</code>
+              up to power the form. Notice that you can still use most features like <code>expressions</code>
               and <code>validators</code> even in a string form.
 
               <br/>

demo/src/app/examples/validation/force-show-error/app.component.ts

@@ -26,7 +26,7 @@ export class AppComponent {
       validation: {
         show: true,
       },
-      expressionProperties: {
+      expressions: {
         'validation.show': 'model.showErrorState',
       },
     },

demo/src/app/examples/validation/toggle-required/app.component.ts

@@ -29,7 +29,7 @@ export class AppComponent {
       validation: {
         show: true,
       },
-      expressionProperties: {
+      expressions: {
         'props.required': 'model.checked',
       },
     },

demo/src/app/examples/validation/toggle-required/config.module.ts

@@ -19,7 +19,7 @@ import { AppComponent } from './app.component';
               description: `
               This is an example of how to toggle <code>required</code> of a field. It uses:
               <ul>
-                <li><code>expressionProperties</code>: to have formly add <code>required</code> to the input field</li>
+                <li><code>expressions</code>: to have formly add <code>required</code> to the input field</li>
                 <li><code>validation.show</code>: to show validation errors even when they the field has not been touched</li>
                 <li><code>validationMessages</code>: to add a globally available validation message</li>
               </ul>

demo/src/app/guides/expression-properties.md

@@ -1,10 +1,6 @@
 # Formly Expressions
 
-You can use `hideExpression` to hide fields dynamically and `expressionProperties` allow you to dynamically change many properties of a field.
-
-## Expression Properties
-
-Expression Properties allows you to dynamically change many properties of a field.
+Expressions allows you to dynamically field properties.
 For example, you can disable a form field dynamically. The value of this property can be `string` or `function`.
 You can see an example using string value [here](https://stackblitz.com/edit/angular-formly-eehxjb?file=app/app.component.ts)
 
@@ -16,7 +12,7 @@ You can see an example using string value [here](https://stackblitz.com/edit/ang
     label: 'Hey!',
     placeholder: 'This one is disabled if there is no text in the other input',
   },
-  expressionProperties: {
+  expressions: {
     'props.disabled': '!model.text',
   },
 },
@@ -33,10 +29,9 @@ Example with function value:
     label: 'field 2',
     placeholder: ''
   },
-  expressionProperties: {
-    'props.disabled': (model: any, formState: any, field: FormlyFieldConfig) => {
-      // access to the main model can be through `this.model` or `formState` or `model`
-      return !formState.mainModel.text
+  expressions: {
+    'props.disabled': (field: FormlyFieldConfig) => {
+      return !field.model.text;
     },
   }
 }
@@ -57,7 +52,7 @@ options = {
 
 ## Conditional Rendering
 
-The `hideExpression` property is used to set the hide property of your field. The value of this property can be `string`, `function` or `boolean`. Below is an example of each of them.
+The `hide` property is used to set the hide property of your field. The value of this property can be a `boolean`. To make this property conditional we'll use `expressions: { hide: ... }` where the value can  `string`, `function` or `boolean`. Below is an example of each of them.
 
 First option with *string value*:
 
@@ -69,7 +64,7 @@ You can see an example [here](https://stackblitz.com/edit/angular-formly-f79kb3?
   props: {
     label: 'I like twix',
   },
-  hideExpression: '!model.name',
+  expressions: { hide: '!model.name' },
 }
 ```
 Second option with *function value*:
@@ -81,16 +76,14 @@ You can see an example [here](https://stackblitz.com/edit/angular-formly-ndfcmz?
   key: 'country',
   type: 'input',
   props: {
-    label: 'City',
-    placeholder: 'set to 123'
-  },
-  hideExpression: (model: any, formState: any, field: FormlyFieldConfig) => {
-    // access to the main model can be through `this.model` or `formState` or `model`
-    if (formState.mainModel && formState.mainModel.city) {
-      return formState.mainModel.city !== "123"
-    }
-    return true;
+    label: 'Country',
+    placeholder: 'set city field to 123'
   },
+  expressions: {
+    hide: (field: FormlyFieldConfig) => {
+      return field.model?.city === "123";
+    },
+  }
 },
 ```
 
@@ -111,12 +104,10 @@ fields: FormlyFieldConfig[] = [
       label: 'Street',
       placeholder: ''
     },
-    hideExpression: this.show
   },
 ];
 
 toggle(){
-  this.show = !this.show;
-  this.fields[1].hideExpression = this.show;
+  this.fields[0].hide = !this.fields[0].hide;
 }
 ```

demo/src/app/guides/properties-options.md

@@ -38,12 +38,13 @@ Everything starts with the `formly-form`. General use of it will look something
 | type                 | `string`     | The `type` of field to be rendered. More information over at Custom templates. |
 | className            | `string`     | You can specify your own class that will be applied to the `formly-field` directive. |
 | props      | `object`     | This is reserved for the templates. Any template-specific options go in here. Look at your specific template implementation to know the options required for this. |
+| templateOptions      | `object`     | This is reserved for the templates. Any template-specific options go in here. Look at your specific template implementation to know the options required for this. @deprecated use `props` instead |
 | template             | `string`     | Can be set instead of `type` to render custom `html` content. |
 | defaultValue         | `any` | If this is provided and the value of the model at compile-time is `undefined`, then the value of the model will be assigned the defaultValue. |
-| hide                 | `boolean`    | Whether to hide the field. Defaults to false. If you wish this to be conditional use `hideExpression`. |
-| hideExpression       | `boolean`/`string`/`function` | Conditionally hide the field based on values from other fields. |
-| expressionProperties | `boolean`/`string`/`function` | An object where the key is a property to be set on the main field config and the value is an expression used to assign that property. |
-| focus                | `boolean`    | Whether to focus or blur the element field. Defaults to false. If you wish this to be conditional use `expressionProperties` |
+| hide                 | `boolean`    | Whether to hide the field. Defaults to false. If you wish this to be conditional use `expressions: { hide: ... }`. |
+| hideExpression       | `boolean`/`string`/`function` | Conditionally hide the field based on values from other fields. @deprecated use `expressions: { hide: ... }` instead |
+| expressions | `boolean`/`string`/`function` | An object where the key is a property to be set on the main field config and the value is an expression used to assign that property. |
+| focus                | `boolean`    | Whether to focus or blur the element field. Defaults to false. If you wish this to be conditional use `expressions` |
 | wrappers             | `string[]`   | It is expected to be the name of the wrappers. The formly field template will be wrapped by the first wrapper, then the second, then the third, etc. You can also specify these as part of a type (which is the recommended approach). |
 | parsers              | `function[]` | Array of functions to execute, as a pipeline, whenever the model updates, usually via user input. |
 | fieldGroup           | `FormlyFieldConfig[]` | A field group is a way to group fields together, making advanced layout very simple. It can also be used to group fields that are associated with the same model (useful if it's different than the model for the rest of the fields). |

demo/src/assets/json-powered/user-form_json

@@ -34,9 +34,9 @@
     "props": {
       "label": "Why?"
     },
-    "expressionProperties": {
+    "expressions": {
+      "hide": "!model.color",
       "props.label": "'Why did you choose ' + model.color + '?'"
-    },
-    "hideExpression": "!model.color"
+    }
   }
 ]