Web AngularJS - angular-formly study notes

  Web  Comments

Angular formly 運作原理

將 form 中的每個 field 獨立出來寫成共用 template，並供整個 app 使用。使用者先在 angular-formly 中進行 configuration，包含設定 type 和 wrapper ，接著只要在 component 的 controller 中建立指定 type 的 field objects 之後，angular-formly 就會結合之前設定好的 field template 和 objects， render 出完整的表單。 ![study.png]({{ site.url }}/assets/images/angular-formly-usage-1.png)

Angular-formly field render source code

Angular-formly 套用 field template 的順序流程：

 1getFieldTemplate(scope.options)
 2      .then(runManipulators(fieldManipulators.preWrapper))
 3      .then(transcludeInWrappers(scope.options, scope.formOptions))
 4      .then(runManipulators(fieldManipulators.postWrapper))
 5      .then(setElementTemplate)
 6      .then(watchFormControl)
 7      .then(callLinkFunctions)
 8      .catch(error => {
 9        formlyWarn(
10          'there-was-a-problem-setting-the-template-for-this-field',
11          'There was a problem setting the template for this field ',
12          scope.options,
13          error
14        )
15      })

Set Up Field Templates

- Prebuilt Template

在使用 angular-formly 之前必須先定義好各 field 的 template。目前有幾個已經建好的簡易 formly template，包含：

  1. Boostrap
  2. LumX
  3. lonic

不過目前這些 template module 都已經沒在維護，所以還是自己寫一個 template 比較妥當。

Pre-built template 使用方式

1import 'angular-formly-templates-bootstrap';
2// inject to the module
3.module('myApp', ['formly', 'formlyBootstrap']);

[Notice] 使用之前，請先看 template 的 source code，確認好有哪些 type 有被定義，不然會報錯。（例如: formlyBootstrap 並沒有定義switch type，因此無法使用。）

- Use Custom Template

API Documents: formlyConfig

使用 formlyConfig 或 formlyConfigProvider 來定義自己的 field template。

Example1: use formlyConfig

在 module.run 中設定的好處是，可以 inject 其他想要的 service。

1module.run((formlyConfig, MyService) => {
2  formlyConfig.setType({
3    // Set a type object.
4    // MyService could be used in controller.
5  });
6});
Example2: use formlyConfigProvider

在 cinfig 階段設定，則無法引入 service ，因為該階段 service 還未被建立。

1module.config(formlyConfigProvider => {
2  formlyConfigProvider.setType({
3    // Set a type object.
4    // You cannot inject your services in a config stage.
5  });
6});

API Reference

1. setType

Example 1:
1formlyConfig.setType({
2  // 定義 field type
3  name: 'input',
4  template: '<input ng-model="model[options.key]" />'
5  // 必須使用 model[options.key]，因為是要指定 options.key 的值為 model 對象
6});
Example 2:
 1formlyConfig.setType({
 2  name: 'ipAddress',
 3  extends: 'input',
 4  // 用來包裝 field template 的 wrapper template.
 5  wrapper: 'someWrapper',
 6  // 加入自訂 property。
 7  defaultOptions: {},
 8  link: function(scope, el, attrs) {},
 9  // 該controller 的觸發時間為 formly-field(internal API) 之後，field controller 之前。
10  controller: function($scope, yourInjectableThing) {},
11  // 欄位驗證
12  apiCheck: {}
13});

[Notice] Just be aware that angular-formly does make use of common parameters like required or onClick to automatically add attributes to ng-model elements.

Some properties of config:

  • name field refernece.(Required!)
  • templateUrl or template (use $templateCache) 套用於該 field 的 template(通常是HTML格式).
  • wrapper 額外加入 template 在 field template 外層。
  • apiCheck Default setting uses apiCheck library.
*Example for apiCheck:
1apiCheck: check => ({
2          templateOptions: {
3            label: check.string.optional,
4            required: check.bool.optional,
5            labelSrOnly: check.bool.optional,
6          }
7        })

  • extend (需注意如果在 extend type 設置和母 type 一樣的 wrapper 會造成衝突，請重新設置一個新的type。)

  • defaultOptions 在該欄位中加入自定義的 options 供使用者調整。

*Example for defaultOptions:
1defaultOptions: {
2  ngModelAttrs: {
3    // 在 type的 attribute 中加入 rows 和 mdMaxLength 屬性。
4    rows: {attribute: 'rows'},
5    mdMaxLength: {attribute: 'md-maxlength'}
6  }
7}

2. setWrapper

定義 wrapper 的寫法和定義 field 寫法雷同，不過template 中需加入指定 html tag。

  • 需使用 <formly-transclude></formly-transclude> 來指定 field template 的位置。
  • 至少要有 templateUrl 或 template。
*wapper template example：
1<div>
2  <label>
3    {{to.label}}
4    {{to.required ? '*' : ''}}
5  </label>
6  <!-- 需使用<formly-transclude> 來指定 field template 放置的位置 -->
7  <formly-transclude></formly-transclude>
8</div>

###[ 其他重點 ] Template’s $scope

在寫 controller 或 expressionProperties function 的時候，可以使用$scope 來操作 template 中的變數。這邊要注意的是， angular-formly 的 $scope 有調整過，新增一些 formly 特有屬性，所以要使用指定的 property 去取得 model 參數。

常用的property

Variable Name Description
options 此 object 包含設定 field 的參數，例如: formControl, initModel等。
to = options.templateOptions
fc = options.formControl
*template’s $scope example 1
1<label>{{ to.label }}</label>
*template’s $scope example 2
 1  key: 'priority',
 2  type: 'radio',
 3  defaultValue: this.item.priority || 1,
 4  templateOptions: {
 5    label: 'Priority',
 6    options: []
 7  },
 8  controller: function($scope) {
 9    $scope.to.options = [
10      { value: 1, label: 'Urgent' },
11      { value: 2, label: 'Normal' }
12    ];
13  }

Field configuration

Property

  • key key 會與 controller 的 model 綁定(controller.model.keyName)。預設 key 值是 field object array 的 index。
  • type 這個是指欄位的型別，例如 input / checkbox / switch / select 等。注意：type 需在 formlyConfig 被定義，也可直接使用現有的template。
  • templateOption
  • defaultValue initialize model. 如果該 model 在 compile-time 中為 undefined，則會 assign 此初始值。if you want to default values in the form, simply initialize your model with that state and you’re good. However, there are some use cases where it is much easier to use the form config to initialize the model, which is why this property was added.
  • hideExpression (string || function)
  • expressionProperties (object)
  • model 這個用在當 field 的 model 和 formly 的model 為不同的時候。可配合expressionProperties（a deep watch is added to the formly-field directive’s scope to run the expressionProperties when the specified model changes）。