Merge pull request #161 from erqk/v8

Update docs
erqk · Dec 3, 2024 · d44f2e9 · d44f2e9
2 parents d615e30 + 0fa91b4
commit d44f2e9
Show file tree

Hide file tree

Showing 36 changed files with 5,140 additions and 1 deletion.
diff --git a/docs/assets/docs/index.md b/docs/assets/docs/index.md
@@ -0,0 +1,29 @@
+## 8.0.0
+
+- [English](./v8/index_en.md)
+- [繁中](./v8/index_zh-TW.md)
+
+## 5.8.4
+
+- [English](./v5/index_en.md)
+- [繁中](./v5/index_zh-TW.md)
+
+## 4.0.5 (deprecated)
+
+- [English](./v4/index_en.md)
+- [繁中](./v4/index_zh-TW.md)
+
+## 3.4.1 (deprecated)
+
+- [English](./v3/index_en.md)
+- [繁中](./v3/index_zh-TW.md)
+
+## 2.0.1 (deprecated)
+
+- [English](./v2/index_en.md)
+- [繁中](./v2/index_zh-TW.md)
+
+## 1.0.11 (deprecated)
+
+- [English](./v1/index_en.md)
+- [繁中](./v1/index_zh-TW.md)
diff --git a/docs/assets/docs/v8/conditions/conditions_en.md b/docs/assets/docs/v8/conditions/conditions_en.md
@@ -0,0 +1,164 @@
+# Conditions
+
+The conditions will let user to :
+
+- toggle control’s validators
+- toggle control’s visibility
+- toggle control’s disabled state
+- execute custom function
+
+The following example demonstrates the text input is hidden when the checkbox is unchecked.
+
+<doc-form-viewer config-path="CONDITIONS_VISIBILITY.EN"></doc-form-viewer>
+
+## Syntax
+
+The `conditions` is build up by `NAME`, `GROUP_OPERATOR` and a tupple of `[CONTROL_PATH, OPERATOR, VALUE]`.
+
+```ts
+{
+    ...
+    "conditions": {
+      NAME: {
+        GROUP_OPERATOR: [
+          [CONTROL_PATH, OPERATOR, VALUE]
+        ]
+      }
+    }
+  }
+```
+
+### NAME
+
+The available `NAME` are listed as below.
+
+#### Built-in validators
+
+- `validator.required`
+- `validator.requiredTrue`
+- `validator.min`
+- `validator.max`
+- `validator.minLength`
+- `validator.maxLength`
+- `validator.email`
+- `validator.pattern`
+
+#### Control state
+
+- `control.disabled`
+- `control.hidden`
+
+#### Custom validator
+
+- `validators.` + `name`
+
+#### Custom action
+
+- Any string that match with the key inside `conditionsActionFuntions`.
+
+### GROUP_OPERATOR
+
+`&&`, `||`
+
+This is required for every key inside `conditions`. GROUP_OPERATOR accepts tupple or nested GROUP_OPERATOR.
+
+> Only provide `&&` or `||` at one time. If both are present, only `&&` will be chosen.
+
+### LEFT, OPERATOR, RIGHT
+
+The tupple `[LEFT, OPERATOR, RIGHT]` acts as the `if` statement:
+
+```tsx
+// ["controlA", "===", "foo"]
+if (controlA.value === "foo") {...}
+
+// ["controlA,prop1", "===", "foo"]
+if (controlA.value.prop1 === "foo") {...}
+
+// ["groupA.controlA", "===", "foo"]
+if (groupA.controls.controlA.value === "foo") {...}
+
+// ["bar", "!==", "controlB"]
+if (controlB.value !== "bar") {...}
+```
+
+The `OPERATOR` accepts:
+
+- `===`
+- `!==`
+- `>=`
+- `<=`
+- `>`
+- `<`
+- `includes`
+- `notIncludes`
+
+## Execute custom function
+
+Provide `conditionsActionFuntions` with key and function pairs. When the condition met, the corresponding function will be executed.
+
+<doc-tab>
+
+<doc-code name="HTML">
+
+<!-- prettier-ignore -->
+```html
+<ng-dynamic-json-form
+  [configs]="configs"
+  [conditionsActionFuntions]="customActions"
+></ng-dynamic-json-form>
+```
+
+</doc-code>
+
+<doc-code name="TS">
+
+```jsx
+configs = [
+  {
+    ...
+    "conditions": {
+      "doA": {
+        "&&": [...]
+      },
+      "doB": {
+        "&&": [...]
+      }
+    }
+  }
+];
+
+customActions = {
+  doA: () => this._actionA(),
+  doB: (c?: AbstractControl) => this._actionB(c)
+}
+
+private _actionA(): void {
+  ...
+}
+
+// The control is the control where the `conditions` have effect on.
+private _actionB(c?: AbstractControl): void {
+  ...
+}
+```
+
+</doc-code>
+
+</doc-tab>
+
+## Example
+
+### Toggle visibility
+
+<doc-form-viewer config-path="CONDITIONS_VISIBILITY.EN"></doc-form-viewer>
+
+### Toggle validators
+
+To toggle validators, they must exists inside `validators`.
+
+<doc-form-viewer config-path="CONDITIONS_VALIDATOR.EN"></doc-form-viewer>
+
+### Multiple conditions
+
+<doc-form-viewer config-path="CONDITIONS_MULTIPLE.EN"></doc-form-viewer>
diff --git a/docs/assets/docs/v8/conditions/conditions_zh-TW.md b/docs/assets/docs/v8/conditions/conditions_zh-TW.md
@@ -0,0 +1,164 @@
+# 條件
+
+使用條件可處理一下情況：
+
+- 切換欄位的驗證器
+- 切換欄位的顯示
+- 切換欄位的禁用狀態
+- 執行自訂動作
+
+以下例子顯示，當 checkbox 取消勾選之後，則隱藏 input。
+
+<doc-form-viewer config-path="CONDITIONS_VISIBILITY.ZH-TW"></doc-form-viewer>
+
+## 語法
+
+`conditions` 由 `NAME`、`GROUP_OPERATOR` 和一個 tupple `[CONTROL_PATH, OPERATOR, VALUE]` 組成。
+
+```ts
+{
+    ...
+    "conditions": {
+      NAME: {
+        GROUP_OPERATOR: [
+          [CONTROL_PATH, OPERATOR, VALUE]
+        ]
+      }
+    }
+  }
+```
+
+### NAME
+
+以下為可用的 `NAME` 列表。
+
+#### 內建驗證器
+
+- `validator.required`
+- `validator.requiredTrue`
+- `validator.min`
+- `validator.max`
+- `validator.minLength`
+- `validator.maxLength`
+- `validator.email`
+- `validator.pattern`
+
+#### 控制器狀態
+
+- `control.disabled`
+- `control.hidden`
+
+#### 自訂驗證器
+
+- `validators.` + `name`
+
+#### 自訂動作
+
+- `conditionsActionFuntions` 內對應的 key 字串
+
+### GROUP_OPERATOR
+
+`&&`, `||`
+
+每一個 `conditions` 的 key 都必須含有至少一個 GROUP_OPERATOR。可接受 tupple 或巢狀 GROUP_OPERATOR。
+
+> `&&` or `||` 只需則一，若同時提供，只有 `&&` 會被使用。
+
+### LEFT, OPERATOR, RIGHT
+
+Tupple `[LEFT, OPERATOR, RIGHT]` 的作用是作為 `if` 表達式：
+
+```tsx
+// ["controlA", "===", "foo"]
+if (controlA.value === "foo") {...}
+
+// ["controlA,prop1", "===", "foo"]
+if (controlA.value.prop1 === "foo") {...}
+
+// ["groupA.controlA", "===", "foo"]
+if (groupA.controls.controlA.value === "foo") {...}
+
+// ["bar", "!==", "controlB"]
+if (controlB.value !== "bar") {...}
+```
+
+可使用的 `OPERATOR`：
+
+- `===`
+- `!==`
+- `>=`
+- `<=`
+- `>`
+- `<`
+- `includes`
+- `notIncludes`
+
+## 執行自訂動作
+
+將 key 和對應的 function 傳入 `conditionsActionFuntions`。當條件達成，相對於的 function 就會自動被執行。
+
+<doc-tab>
+
+<doc-code name="HTML">
+
+<!-- prettier-ignore -->
+```html
+<ng-dynamic-json-form
+  [configs]="configs"
+  [conditionsActionFuntions]="customActions"
+></ng-dynamic-json-form>
+```
+
+</doc-code>
+
+<doc-code name="TS">
+
+```jsx
+configs = [
+  {
+    ...
+    "conditions": {
+      "doA": {
+        "&&": [...]
+      },
+      "doB": {
+        "&&": [...]
+      }
+    }
+  }
+];
+
+customActions = {
+  doA: () => this._actionA(),
+  doB: (c?: AbstractControl) => this._actionB(c)
+}
+
+private _actionA(): void {
+  ...
+}
+
+// 此 control 是條件達成後，會對其進行操作的 control。
+private _actionB(c?: AbstractControl): void {
+  ...
+}
+```
+
+</doc-code>
+
+</doc-tab>
+
+## 例子
+
+### 切換顯示狀態
+
+<doc-form-viewer config-path="CONDITIONS_VISIBILITY.ZH-TW"></doc-form-viewer>
+
+### 切換驗證器
+
+若要切換驗證器，該驗證器必須存在於 `validators` 陣列內。
+
+<doc-form-viewer config-path="CONDITIONS_VALIDATOR.ZH-TW"></doc-form-viewer>
+
+### 多個條件
+
+<doc-form-viewer config-path="CONDITIONS_MULTIPLE.ZH-TW"></doc-form-viewer>