JSON スキーマを使用したアダプティブフォームの作成 creating-adaptive-forms-using-json-schema
前提条件 prerequisites
JSON スキーマをフォームモデルとして使用してアダプティブフォームをオーサリングする場合は、JSON スキーマの基本的な理解が必要です。 この記事を読む前に、以下のコンテンツを読んでおくことをお勧めします。
フォームモデルとしての JSON スキーマの使用 using-a-json-schema-as-form-model
AEM Formsは、既存の JSON スキーマをフォームモデルとして使用したアダプティブフォームの作成をサポートしています。 JSON スキーマは、組織内のバックエンドシステムによってデータが作成または使用される構造を表します。使用する JSON スキーマは、v4 仕様に準拠している必要があります。
JSON スキーマを使用する主な機能は次のとおりです。
- JSON の構造は、アダプティブフォームのオーサリングモードの「コンテンツファインダー」タブにツリーとして表示されます。 JSON 階層からアダプティブフォームに要素をドラッグして追加することができます。
- 関連付けられたスキーマに準拠する JSON を使用して、フォームに事前入力できます。
- ユーザーが入力したデータは、送信時には関連付けられたスキーマに適合する JSON として送信されます。
JSON スキーマは、単純な要素タイプと複雑な要素タイプで構成されます。 要素には、その要素にルールを追加する属性が含まれています。これらの要素と属性がアダプティブフォームにドラッグされると、対応するアダプティブフォームコンポーネントに自動的にマッピングされます。
この JSON 要素とアダプティブフォームコンポーネントのマッピングは、次のようになります。
共通のスキーマプロパティ common-schema-properties
アダプティブフォームは JSON スキーマで使用可能な情報を使用して、生成された各フィールドをマッピングします。具体的には、以下のようになります。
- title プロパティは、アダプティブフォームコンポーネントのラベルとして機能します。
- description プロパティは、アダプティブフォームコンポーネントの詳細な説明として設定されます。
- default プロパティは、アダプティブフォームフィールドの初期値として機能します。
- maxLength プロパティは、テキストフィールドコンポーネントの maxlength 属性として設定されます。
- minimum、maximum、exclusiveMinimum および exclusiveMaximum プロパティは、数値ボックスコンポーネントに使用されます。
- DatePicker コンポーネントの範囲をサポートするために、JSON スキーマの追加のプロパティ minDate および maxDate が提供されます。
- minItems プロパティと maxItems プロパティを使用して、パネルコンポーネントに追加または削除できる項目/フィールドの数を制限します。
- readOnly プロパティは、アダプティブフォームコンポーネントの readonly 属性を設定します。
- 必須プロパティはアダプティブフォームフィールドを必須としてマークします。一方、パネル（タイプはオブジェクト）の場合、最終的に送信される JSON データは、そのオブジェクトに対応する空の値を持つフィールドを持ちます。
- pattern プロパティは、アダプティブフォームの検証パターン（正規表現）として設定されます。
- JSON スキーマファイルの拡張子は、.schema.json を維持する必要があります。例えば、<filename>.schema.json のように指定します。
JSON スキーマのサンプル sample-json-schema
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"
}
}
}
再使用可能なスキーマ定義 reusable-schema-definitions
定義キーを使用して、再使用可能なスキーマを識別します。再使用可能なスキーマ定義を使用して、フラグメントを作成します。これは、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 スキーマ定義でのフィールドの事前設定 pre-configuring-fields-in-json-schema-definition
aem:afProperties プロパティを使用して JSON スキーマのフィールドを事前構成し、カスタムのアダプティブフォームコンポーネントにマップできます。以下に例を示します。
{
"properties": {
"sizeInMB": {
"type": "integer",
"minimum": 16,
"maximum": 512,
"aem:afProperties" : {
"sling:resourceType" : "/apps/fd/af/components/guideTextBox",
"guideNodeClass" : "guideTextBox"
}
}
},
"required": [ "sizeInMB" ],
"additionalProperties": false
}
アダプティブフォームコンポーネントで許容される値の制限 limit-acceptable-values-for-an-adaptive-form-component
JSON スキーマの要素に次の制限を追加して、アダプティブフォームコンポーネントで許容される値を制限できます。
サポート対象外の構成 non-supported-constructs
アダプティブフォームは、次の JSON スキーマ構成をサポートしていません。
- Null タイプ
- any などの Union タイプ
- OneOf、AnyOf、AllOf、NOT
- 同種の配列のみがサポートされます。そのため、項目制限は、配列でなくオブジェクトである必要があります。
よくある質問 frequently-asked-questions
繰り返し可能なサブフォーム（minOccurs 値または maxOccurs 値が 1 より大きい）では、サブフォーム（任意の複合型から生成された構造）の個々の要素をドラッグできないのはなぜですか？
繰り返し可能なサブフォームでは、完全なサブフォームを使用する必要があります。選択した一部のフィールドのみを使用する場合は、構造全体を使用し、不要部分を削除します。
コンテンツファインダーに長く複雑な構造があります。特定の要素を見つけるにはどうすればよいですか？
以下の 2 つのオプションがあります。
- ツリー構造をスクロールする
- 検索ボックスを使用して、要素を検索する