JSON スキーマを使用したアダプティブフォームの作成

前提条件

フォームモデルとして JSON スキーマを使用してアダプティブフォームをオーサリングする場合、JSON スキーマの基本を理解している必要があります。この記事を読む前に次のコンテンツを読んでおくことをお勧めします。

フォームモデルとしての JSON スキーマの使用

AEM Forms では、既存の JSON スキーマをフォームモデルとして使用したアダプティブフォームの作成がサポートされています。JSON スキーマは、組織のバックエンドシステムによりデータの生成や消費が行われる構造を表しています。The JSON Schema you use should be compliant with v4 specifications.

JSON スキーマの使用の主な特長は、次のとおりです。

  • JSON の構造は、アダプティブフォームのオーサリングモードの「コンテンツファインダー」タブでツリーとして表示されます。JSON 階層からアダプティブフォームに要素をドラッグして追加できます。
  • 関連付けられたスキーマに準拠する JSON を使用して、フォームに事前入力できます。
  • ユーザーが入力したデータは、送信時には関連付けられたスキーマに適合する JSON として送信されます。

JSON スキーマは、単純型要素と複合型要素で構成されています。要素には、その要素にルールを追加する属性が含まれています。これらの要素や属性がアダプティブフォーム上にドラッグされると、自動的に該当するアダプティブフォームコンポーネントにマッピングされます。

JSON 要素とアダプティブフォームコンポーネントのマッピングは、次のように行われます。

"birthDate": {
              "type": "string",
              "format": "date",
              "pattern": "date{DD MMMM, YYYY}",
              "aem:affKeyword": [
                "DOB",
                "Date of Birth"
              ],
              "description": "Date of birth in DD MMMM, YYYY",
              "aem:afProperties": {
                "displayPictureClause": "date{DD MMMM, YYYY}",
                "displayPatternType": "date{DD MMMM, YYYY}",
                "validationPatternType": "date{DD MMMM, YYYY}",
                "validatePictureClause": "date{DD MMMM, YYYY}",
                "validatePictureClauseMessage": "Date must be in DD MMMM, YYYY format."
              }
JSON の要素、プロパティ、属性 アダプティブフォームコンポーネント

enum制約とenumNames制約を含む文字列プロパティ。

構文,

{

"type" : "string",

"enum" : ["M", "F"]

"enumNames" : ["Male", "Female"]

}

ドロップダウンコンポーネント:

  • enumNames にリストされた値はドロップボックスに表示されます。
  • enum にリストされた値は計算に使用されます。

フォーマット制限付きの文字列プロパティ。例えば、電子メール、日付など。

構文,

{

"type" : "string",

"format" : "email"

}

  • タイプが文字列でフォーマットが電子メールのときに、電子メールのコンポーネントがマップされます。
  • タイプが文字列でフォーマットがホスト名のときに、検証付きテキストボックスのコンポーネントがマップされます。

{

"type" : "string",

}



テキストフィールド


number プロパティ
サブタイプが float に設定された数値フィールド
integer プロパティ
サブタイプが integer に設定された数値フィールド
boolean プロパティ
切り替え
object プロパティ
パネル
array プロパティ minItems および maxItems にそれぞれ等しい min および max を持つ繰り返し可能なパネル。同種の配列のみがサポートされます。So the items constraint must be an object and not an array.

共通のスキーマプロパティ

アダプティブフォームは JSON スキーマで使用可能な情報を使用して、生成された各フィールドをマッピングします。具体的には、次のことを実行します。

  • titleプロパティは、アダプティブフォームコンポーネントのラベルとして機能します。
  • descriptionプロパティは、アダプティブフォームコンポーネントの詳細な説明として設定されます。
  • defaultプロパティは、アダプティブフォームフィールドの初期値として機能します。
  • maxLengthプロパティは、テキストフィールドコンポーネントのmaxlength属性として設定されます。
  • minimum、maximum、exclusiveMinimumおよびexclusiveMaximumプロパティは、数値ボックスコンポーネントに使用されます。
  • DatePickerコンポーネントの範囲をサポートするために、minDateとmaxDateの追加のJSONスキーマプロパティが用意されています。
  • minItemsプロパティとmaxItemsプロパティは、パネルコンポーネントに追加または削除できる項目/フィールドの数を制限するために使用します。
  • readOnlyプロパティは、アダプティブフォームコンポーネントの読み取り専用属性を設定します。
  • requiredプロパティはアダプティブフォームフィールドを必須としてマークしますが、typeがobjectの場合は最後の送信JSONデータのフィールドはそのオブジェクトに対応する空の値を持ちます。
  • patternプロパティは、アダプティブフォームで検証パターン(正規式)として設定されます。
  • JSONスキーマファイルの拡張子は。スキーマ.jsonにする必要があります。 例えば、<filename>.スキーマ.jsonのように指定します。

JSON スキーマのサンプル

JSON スキーマの例を示します。

{
 "$schema": "https://json-schema.org/draft-04/schema#",
 "definitions": {
  "employee": {
   "type": "object",
   "properties": {
    "userName": {
     "type": "string"
    },
    "dateOfBirth": {
     "type": "string",
     "format": "date"
    },
    "email": {
     "type": "string",
     "format": "email"
    },
    "language": {
     "type": "string"
    },
    "personalDetails": {
     "$ref": "#/definitions/personalDetails"
    },
    "projectDetails": {
     "$ref": "#/definitions/projectDetails"
    }
   },
   "required": [
    "userName",
    "dateOfBirth",
    "language"
   ]
  },
  "personalDetails": {
   "type": "object",
   "properties": {
    "GeneralDetails": {
     "$ref": "#/definitions/GeneralDetails"
    },
    "Family": {
     "$ref": "#/definitions/Family"
    },
    "Income": {
     "$ref": "#/definitions/Income"
    }
   }
  },
  "projectDetails": {
   "type": "array",
   "items": {
    "properties": {
     "name": {
      "type": "string"
     },
     "age": {
      "type": "number"
     },
     "projects": {
      "$ref": "#/definitions/projects"
     }
    }
   },
   "minItems": 1,
   "maxItems": 4
  },
  "projects": {
   "type": "array",
   "items": {
    "properties": {
     "name": {
      "type": "string"
     },
     "age": {
      "type": "number"
     },
     "projectsAdditional": {
      "$ref": "#/definitions/projectsAdditional"
     }
    }
   },
   "minItems": 1,
   "maxItems": 4
  },
  "projectsAdditional": {
   "type": "array",
   "items": {
    "properties": {
     "Additional_name": {
      "type": "string"
     },
     "Additional_areacode": {
      "type": "number"
     }
    }
   },
   "minItems": 1,
   "maxItems": 4
  },
  "GeneralDetails": {
   "type": "object",
   "properties": {
    "age": {
     "type": "number"
    },
    "married": {
     "type": "boolean"
    },
    "phone": {
     "type": "number",
     "aem:afProperties": {
      "sling:resourceType": "/libs/fd/af/components/guidetelephone",
      "guideNodeClass": "guideTelephone"
     }
    },
    "address": {
     "type": "string"
    }
   }
  },
  "Family": {
   "type": "object",
   "properties": {
    "spouse": {
     "$ref": "#/definitions/spouse"
    },
    "kids": {
     "$ref": "#/definitions/kids"
    }
   }
  },
  "Income": {
   "type": "object",
   "properties": {
    "monthly": {
     "type": "number"
    },
    "yearly": {
     "type": "number"
    }
   }
  },
  "spouse": {
   "type": "object",
   "properties": {
    "name": {
     "type": "string"
    },
    "Income": {
     "$ref": "#/definitions/Income"
    }
   }
  },
  "kids": {
   "type": "array",
   "items": {
    "properties": {
     "name": {
      "type": "string"
     },
     "age": {
      "type": "number"
     }
    }
   },
   "minItems": 1,
   "maxItems": 4
  }
 },
 "type": "object",
 "properties": {
  "employee": {
   "$ref": "#/definitions/employee"
  }
 }
}

再使用可能なスキーマ定義

定義キーを使用して再使用可能なスキーマを識別します。フラグメントの作成には、再利用可能なスキーマ定義が使用されます。 これは、XSD での複合型の識別と同じです。定義付きの JSON スキーマのサンプルは以下のとおりです。

{
  "$schema": "https://json-schema.org/draft-04/schema#",

  "definitions": {
    "address": {
      "type": "object",
      "properties": {
        "street_address": { "type": "string" },
        "city":           { "type": "string" },
        "state":          { "type": "string" }
      },
      "required": ["street_address", "city", "state"]
    }
  },

  "type": "object",

  "properties": {
    "billing_address": { "$ref": "#/definitions/address" },
    "shipping_address": { "$ref": "#/definitions/address" }
  }
}

上記の例では、それぞれの顧客が出荷先と請求先のどちらの住所もある場合の顧客レコードを定義します。どちらの住所も構造(都道府県、市区町村、番地など)が同じ場合は、住所が重複しないようにすることをお勧めします。また、今後変更が行われたときに、簡単にフィールドを追加したり削除したりできます。

JSON スキーマ定義におけるフィールドの事前構成

You can use the aem:afProperties property to preconfigure JSON Schema field to map to a custom adaptive form component. 以下に例を示します。

{
    "properties": {
        "sizeInMB": {
            "type": "integer",
            "minimum": 16,
            "maximum": 512,
            "aem:afProperties" : {
                 "sling:resourceType" : "/apps/fd/af/components/guideTextBox",
                 "guideNodeClass" : "guideTextBox"
             }
        }
    },
    "required": [ "sizeInMB" ],
    "additionalProperties": false
}

フォームオブジェクトのスクリプトまたは式の設定

アダプティブフォームの式言語はJavascriptです。すべての数式は有効なJavaScriptの数式で、アダプティブフォームのスクリプトモデルAPIを使用しています。フォームイベント上の式を 評価するために、フォームオブジェクトを事前設定できます

aem:afpropertiesプロパティを使用して、アダプティブフォームコンポーネントのアダプティブフォーム式またはスクリプトを事前設定します。 例えば、initializeイベントがトリガされると、次のコードは電話フィールドの値を設定し、ログに値を出力します。

"telephone": {
  "type": "string",
  "pattern": "/\\d{10}/",
  "aem:affKeyword": ["phone", "telephone","mobile phone", "work phone", "home phone", "telephone number", "telephone no", "phone number"],
  "description": "Telephone Number",
  "aem:afProperties" : {
    "sling:resourceType" : "fd/af/components/guidetelephone",
    "guideNodeClass" : "guideTelephone",
    "events": {
      "Initialize" : "this.value = \"1234567890\"; console.log(\"ef:gh\") "
    }
  }
}

フォームオブジェクトのスクリプトまたは 式を設定するには、 forms-power-userグループのメンバーである必要があります。 次の表に、アダプティブフォームコンポーネントでサポートされるすべてのスクリプトイベントを示します。

コンポーネント\イベント initialize
Calculate 視認性 Validate Enabled 値コミット クリック オプション
テキストフィールド
数値フィールド
数値ステッパー
ラジオボタン
電話番号
切り替え
ボタン
チェックボックス
ドロップダウン
画像選択
データ入力フィールド
日付選択
電子メール
添付ファイル
画像
図面
パネル

JSON内でのイベントの使用例としては、初期化イベント時にフィールドを非表示にし、値コミットイベント時に別のフィールドの値を設定する例があります。 スクリプトイベント用の式の作成に関する詳細は、「 アダプティブフォーム式」を参照してください。

前述の例のサンプルJSONコードを以下に示します。

initializeイベントでのフィールドの非表示

"name": {
    "type": "string",
    "aem:afProperties": {
        "events" : {
            "Initialize" : "this.visible = false;"
        }
    }
}

値コミットイベントで別のフィールドの値を設定

"Income": {
    "type": "object",
    "properties": {
        "monthly": {
            "type": "number",
            "aem:afProperties": {
                "events" : {
                    "Value Commit" : "IncomeYearly.value = this.value * 12;"
                }
            }
        },
        "yearly": {
            "type": "number",
            "aem:afProperties": {
                "name": "IncomeYearly"
            }
        }
    }
}

アダプティブフォームコンポーネントで許容される値の制限

JSONスキーマ要素に次の制限を追加して、アダプティブフォームコンポーネントに許容される値を制限することができます。

スキーマプロパティ

データタイプ

説明

コンポーネント

maximum

String

数値および日付の上限を指定します。デフォルトでは、最大値が含まれます。

  • 数値ボックス
  • 数値ステッパー
  • 日付選択

minimum

String

数値および日付の下限を指定します。デフォルトでは、最小値が含まれます。

  • 数値ボックス
  • 数値ステッパー
  • 日付選択

exclusiveMaximum

Boolean

true の場合、フォームのコンポーネントで指定された数値または日付は、maximum プロパティに指定された数値または日付よりも小さい値である必要があります。

false の場合、フォームのコンポーネントで指定された数値または日付は、maximum プロパティに指定された数値または日付以下の値である必要があります。

  • 数値ボックス
  • 数値ステッパー
  • 日付選択

exclusiveMinimum

Boolean

true の場合、フォームのコンポーネントで指定された数値または日付は、minimum プロパティに指定された数値または日付よりも大きい値である必要があります。

false の場合、フォームのコンポーネントで指定された数値または日付は、minimum プロパティに指定された数値または日付以上の値である必要があります。

  • 数値ボックス
  • 数値ステッパー
  • 日付選択

minLength

String

コンポーネントで許可される最小文字数を指定します。最小の長さは 0 以上である必要があります。

  • テキストボックス
maxLength String コンポーネントで許可される最大文字数を指定します。最大の長さは 0 以上である必要があります。
  • テキストボックス

pattern

String

文字のシーケンスを指定します。文字が指定されたパターンに適合すると、コンポーネントはその文字を受け入れます。

この pattern プロパティは、対応するアダプティブフォームコンポーネントの検証パターンにマッピされます。

  • XSDスキーマにマップされているすべてのアダプティブフォームコンポーネント
maxItems String 配列の項目の最大数を指定します。項目の最大数は 0 以上である必要があります。
minItems String 配列の項目の最小数を指定します。項目の最小数は 0 以上である必要があります。

サポート対象外の構成

アダプティブフォームは以下の JSON スキーマ構成をサポートしていません。

  • Null タイプ
  • any、and などの Union タイプ
  • OneOf、AnyOf、AllOf、NOT
  • 同種の配列のみがサポートされます。そのため、項目制限は配列でなくオブジェクトに行われる必要があります。

よくある質問

繰り返し可能なサブフォーム(minOccours 値または maxOccurs 値が 1 より大きい)では、サブフォーム(任意の複合型から生成された構造)の個々の要素をドラッグできないのはなぜですか?

繰り返し可能なサブフォームでは、完全なサブフォームを使用する必要があります。選択した一部のフィールドのみを使用する場合は、構造全体を使用し、不要部分を削除します。

コンテンツファインダーに長く複雑な構造があります。特定の要素を見つけるにはどうすればよいですか?

次の 2 つのオプションがあります。

  • ツリー構造をスクロールします。
  • 「検索」ボックスを使用して、要素を検索します。

JSONスキーマファイルの拡張子は何ですか。

JSONスキーマファイルの拡張子は。スキーマ.jsonにする必要があります。 例えば、<filename>.スキーマ.jsonのように指定します。

このページ