アダプティブフォームの操作のベストプラクティス best-practices-for-working-with-adaptive-forms

Apache Maven aem-project-archetype を使用して、AEM プロジェクトの構造を作成および管理します。AEM プロジェクトに合わせて、推奨される構造およびテンプレートを作成します。さらに、ビルドを自動化し、変更制御システムを提供するので、プロジェクト管理が容易になります。

• Maven archetype:generate コマンドを使用して、最初の構造を生成します。
• Maven eclipse:eclipse コマンドを使用して eclipse プロジェクトファイルを生成し、プロジェクトを eclipse 内に読み込みます。

FileVault ツール（VLT）は、CRX や AEM インスタンスをファイルシステムにマッピングするのに役立ちます。AEM プロジェクトコンテンツのチェックインやチェックアウトなどの変更制御を管理する操作を提供します。VLT ツールの使用方法を参照してください。

Eclipse 統合開発環境を使用している場合、AEM 開発者ツールを使用して Eclipse IDE を AEM インスタンスにシームレスに統合して、AEM アプリケーションを作成できます。詳しくは、Eclipse 用 AEM 開発者ツールを参照してください。

/libs フォルダーにコンテンツを格納したり、変更を加えたりしないでください。/app フォルダーにオーバーレイを作成して、デフォルトの機能を拡張または上書きします。

コンテンツを移動するパッケージを作成する場合は、パッケージのフィルターパスが正しく、必要なパスのみが記載されていることを確認します。

/libs フォルダーにコンテンツを格納したり、変更を加えたりしないでください。/app フォルダーにオーバーレイを作成して、デフォルトの機能を拡張または上書きします。

パッケージの正しい依存関係を定義し、事前に決定されたインストール順序／シーケンスを強制します。

/libs または /apps 内に参照可能なノードを作成しないでください。

アダプティブフォームテンプレートとは、アダプティブフォームの構造およびヘッダーとフッターの情報を定義する特別な AEM ページです。テンプレートのアダプティブフォーム用レイアウト、スタイル、基本構造は事前に設定されています。AEM Forms には、アダプティブフォームの作成にすぐに使用できるテンプレートおよびコンポーネントが用意されています。ただし、必要に応じてカスタムのテンプレートやコンポーネントを作成できます。アダプティブフォームで今後必要となる追加のテンプレートやコンポーネントの要件を収集しておくことをお勧めします。詳しくは、アダプティブフォームおよびコンポーネントのカスタマイズを参照してください。

CRX パッケージマネージャーのユーザーインターフェイスではなくフォームマネージャーユーザーインターフェイスを使用して、フォームパッケージをアップロードすることをお勧めします。CRX パッケージマネージャー経由でパッケージをアップロードすると、異常が発生する場合があるからです。

AEM Forms では、次のフォームモデルに基づいてアダプティブフォームを作成できます。フォームモデルは、フォームと AEM システム間のデータ交換のためのインターフェイスとして機能し、アダプティブフォーム内外のデータフローの XML ベースの構造を提供します。また、フォームモデルはスキーマおよび XFA 制約の形式で、アダプティブフォームにルールや制約を課します。

• なし：このオプションを使用して作成されたアダプティブフォームは、フォームモデルを使用しません。このようなフォームで生成されるデータ XML は、フィールドと対応する値を持つフラットな構造です。
• XML または JSON スキーマ：XML スキーマと JSON スキーマは、組織内のバックエンドシステムによって生成されて使用されるデータの構造を表します。アダプティブフォームにスキーマを関連付け、そのスキーマの要素を使用することにより、アダプティブフォームに動的なコンテンツを追加することができます。スキーマの要素は、アダプティブフォームを作成する際に、コンテンツブラウザーの「データモデルオブジェクト」タブで使用できます。スキーマ要素をドラッグ＆ドロップしてフォームを作成できます。
• XFA フォームテンプレート：これまで XFA ベースの HTML5 フォームに投資してきた場合、これが最適なフォームデータモデルです。XFA ベースのフォームをアダプティブフォームに直接変換できます。すべての既存の XFA ルールは、関連付けられたアダプティブフォームに保持されます。得られたアダプティブフォームは、検証、イベント、プロパティ、パターンなどの XFA 構成をサポートします。
• フォームデータモデル：データベース、web サービス、AEM ユーザープロファイルなどのバックエンドシステムを統合し、アダプティブフォームに事前入力して、送信されたフォームデータをバックエンドシステムに再び書き込む場合は、このフォームモデルが適しています。フォームデータモデルエディターにより、アダプティブフォームの作成に使用できるフォームデータモデルで、エンティティとサービスを定義して設定できます。詳しくは、AEM Forms のデータ統合を参照してください。

AEM Forms には、アダプティブフォームの作成にすぐに使用できる標準のアダプティブフォームテンプレートが用意されています。独自のテンプレートを作成することも可能です。AEM では、静的テンプレートと編集可能テンプレートを使用できます。

• 静的テンプレートは、開発者が定義し、設定します。
• 編集可能テンプレートは、作成者がテンプレートエディターを使用して作成します。テンプレートエディターを使用すれば、テンプレートで基本構造と初期コンテンツを定義できます。構造レイヤーに加えられた変更内容は、そのテンプレートを使用しているすべてのフォームに反映されます。初期コンテンツには、事前設定されたテーマ、事前入力サービス、送信アクションなどが含まれます。ただし、これらの設定はフォームエディターを使用したフォームに対して変更することができます。詳しくは、アダプティブフォームテンプレートを参照してください。

特定のフィールドやパネルインスタンスにスタイルを設定するには、インラインスタイルを使用します。または、CSS ファイルでクラスを定義し、コンポーネントの CSS クラスプロパティでクラス名を指定できます。

コンポーネントにクライアントライブラリを含めて、そのコンポーネントを使用するアダプティブフォームやフラグメントに一貫したスタイルを適用します。詳しくは、アダプティブフォームのページコンポーネントを作成を参照してください。

アダプティブフォームコンテナのプロパティで、CSS ファイルパスフィールド内のクライアントライブラリへのパスを指定することで、選択したアダプティブフォームに、クライアントライブラリで定義したスタイルを適用します。

スタイルのクライアントライブラリを作成するには、テーマエディターのベース clientlib またはフォームコンテナプロパティで、カスタム CSS ファイルを設定します。

アダプティブフォームには、レスポンシブ、タブ付き、アコーディオン、ウィザードなどのパネルレイアウトが用意されており、フォームコンポーネントをパネルにレイアウトする方法を制御できます。カスタムパネルレイアウトを作成して、フォーム作成者が使用できるようにすることができます。詳しくは、アダプティブフォームのカスタムレイアウトコンポーネントの作成を参照してください。

フィールドやパネルレイアウトなど、アダプティブフォームの特定のコンポーネントをカスタマイズすることもできます。

• AEM のオーバーレイ機能を使用してコンポーネントのコピーを変更します。デフォルトのコンポーネントを変更することはお勧めしません。
• /libs のすぐに使用できるアダプティブフォームコンポーネントのレイアウトをカスタマイズするには、デフォルトレイアウトに加えて、カスタマイズレイアウトコンポーネントを作成します。
• カスタムのウィジェットやアピアランスを作成することにより、カスタムのインタラクティブ機能を導入します。デフォルトのコンポーネントを変更することはお勧めしません。詳しくは、アピアランスのフレームワークを参照してください。

PII データの取り扱いに関するレコメンデーションについては、個人を特定できる情報の取り扱いを参照してください。

フォーム階層の下位にあるフィールドにすばやくアクセスするには、サイドバーのオブジェクトブラウザーを使用します。検索ボックスを使用してフォームまたはオブジェクトツリー内のオブジェクトを検索し、オブジェクト間を移動することができます。

サイドバーのコンポーネントブラウザーでコンポーネントのプロパティを表示して編集するには、コンポーネントを選択して をクリックします。コンポーネントをダブルクリックして、そのプロパティをプロパティブラウザーに表示することもできます。

フォームに対する操作をすばやく実行するには、キーボードショートカットを使用します。AEM Forms のキーボードショートカットを参照してください。

アダプティブフォームのコンポーネントは、アダプティブフォームのページでのみ使用することをお勧めします。これらのコンポーネントは、その親階層に対して依存関係を持っています。このため、AEM ページではこれらのコンポーネントを使用しないでください。

ルールの記述時には、フォームフィールドおよびコンポーネントには意味のある一意の名前を使用し、名前の競合を回避します。

ルールの式で、コンポーネント自身を参照するには、コンポーネントの this 演算子を使用します。これにより、コンポーネント名が変更されても、ルールは有効なままになります。例えば、field1.valueCommit script: this.value > 10 のようになります。

他のフォームコンポーネントを参照する場合には、コンポーネント名を使用します。フィールドまたはコンポーネントの値を取得するには、value プロパティを使用します。例えば、field1.value のようになります。

競合を回避するために、コンポーネントは固有の相対階層で参照します。例えば、parentName.fieldName のようになります。

複雑なルールやよく使用するルールを扱う場合は、指定できアダプティブフォーム間で再利用できる別個のクライアントライブラリの機能としてビジネスロジックを作成することを検討します。クライアントライブラリは独立のライブラリとし、jQuery および Underscore.js 以外の外部依存はなくす必要があります。クライアントライブラリは、送信されたフォームデータのサーバーサイドの再検証を実行するために使用することもできます。

アダプティブフォームが提供する一連の API を使用して、アダプティブフォームと通信したり、アダプティブフォーム上でアクションを実行したりできます。主要な API には次の項目が挙げられます。詳しくは、アダプティブフォームの JavaScript ライブラリ API リファレンスを参照してください。

• guideBridge.reset()：フォームをリセットします。

• guideBridge.submit()：フォームを送信します。

• guideBridge.setFocus(somExp, focusOption, runCompletionExp)：フィールドにフォーカスを設定します。

• guideBridge.validate(errorList, somExpression, focus)：フォームを検証します。

• guideBridge.getDataXML(options)：フォームデータを XML として取得します。

• guideBridge.resolveNode(somExpression)：フォームオブジェクトを取得します。

• guideBridge.setProperty(somList, propertyName, valueList)：フォームオブジェクトのプロパティを設定します。

• 上記に加えて、以下のフィールドプロパティを使用できます。

  • field.value でフィールドの値を変更します。
  • field.enabled でフィールドを有効／無効にします。
  • field.visible でフィールドの表示／非表示を変更します。

アダプティブフォームの作成者は、フォーム内のビジネスロジックをビルドするために、場合によっては JavaScript コードを作成する必要があります。JavaScript は強力で効果的ですが、セキュリティ上の期待事項を損なう可能性があります。このため、フォーム作成者が信頼できる人物であることや、フォームを本番稼動させる前に JavaScript コードをレビューし承認するプロセスがあることを確認する必要があります。管理者は、各ユーザーの役割や職務に基づいて、ユーザーグループのルールエディターへのアクセスを制限できます。選択したユーザーグループにルールエディターへのアクセスを許可を参照してください。

ルール内で数式を使用して、アダプティブフォームを動的にすることができます。すべての式は、有効な JavaScript™ の式で、アダプティブフォームのスクリプトモデル API を使用しています。これらの式は、特定のタイプの値を返します。数式およびベストプラクティスについて詳しくは、アダプティブフォームの式を参照してください。

アドビでは、ルールエディターでルールを作成する際に、非同期操作よりも JavaScript 同期操作を使用することをお勧めしています。非同期操作を使用しないことを強くお勧めします。ただし、非同期操作が避けられない状況である場合は、JavaScript のクロージャ関数を実装する必要があります。これにより、潜在的な競合状態に対して効果的に保護し、ルールの実装が最適なパフォーマンスを提供し、全体を通して安定性を維持できるようになります。

例えば、外部 API からデータを取得し、そのデータに基づいてルールを適用する必要があるとします。クロージャを使用して非同期 API 呼び出しを処理し、データを取得した後でルールが適用されるようにします。次にサンプルコードを示します。

     function fetchDataFromAPI(apiEndpoint, callback) {
      // Simulate asynchronous API call with setTimeout
      setTimeout(() => {
        // Assuming the API call is successful, we receive some data
        const data = {
          someValue: 42,
        };
        // Invoke the callback with the fetched data
        callback(data);
      }, 2000); // Simulate a 2-second delay for the API call
    }
    // Rule implementation using Closure
    function ruleImplementation(apiEndpoint) {
      // Using a closure to handle the asynchronous API call and rule application
      // say you have set this value in street field inside address panel
      var streetField = address.street;
      fetchDataFromAPI(apiEndpoint, (data) => {
        streetField.value = data.someValue;
      });
    }
    // Example usage of the rule implementation
    const apiEndpoint = "https://example-api.com/data";
    ruleImplementation(apiEndpoint);

この例では、fetchDataFromAPI で、setTimeout を使用して非同期 API 呼び出しをシミュレートします。データが取得されると、指定されたコールバック関数が呼び出されます。これは、後続のルールアプリケーションを処理するためのクロージャです。ruleImplementation 関数には、ルールロジックが含まれます。

可能な場合には、XFA をアダプティブフォームに変換する場合でも、XSD フォームデータモデルを使用してアダプティブフォームを作成することをお勧めします。

アダプティブフォームには、ユーザーからの情報を取得するフィールドとパネルのみを含めます。静的コンテンツを最小限に抑えるか、URL を使用してそれらを別のウィンドウで開くことを検討します。

すべてのフォームは特定の目的のためにデザインされますが、ほとんどのフォームにはいくつかの共通するセグメントがあります。例えば、個人の詳細、住所、雇用の詳細などです。フォームの共通の要素およびセクションに対してアダプティブフォームフラグメントを作成し、それらを複数のフォーム間で使用します。パネルをフラグメントとして既存のフォーム内に保存することもできます。フラグメント内の変更はすべて、関連付けられたアダプティブフォームに反映されます。これにより、複数の作成者が同時に、1 つのフォームを構成する別のフラグメントの作業を行えるため、オーサリングの共同作業が促進されます。

• アダプティブフォームと同様に、フラグメント固有のすべてのスタイル設定およびカスタムスクリプトは、フラグメントコンテナダイアログを使用して、クライアントライブラリで定義することをお勧めします。また、外部のオブジェクトに依存しない自己完結型のフラグメントを作成するようにしてください。
• フラグメントをまたぐスクリプトは使用しないでください。フラグメントの外部に参照する必要があるオブジェクトが存在する場合、そのオブジェクトが親フォームの一部となるようにします。それでもオブジェクトが別のフラグメントに存在しなくてはならない場合、スクリプト中でその名前を参照します。

自動保存機能のある「保存して再開」を使用して、アダプティブフォームを定期的に保存し、ユーザーが後で再度訪問してフォームを完了できるようにします。

フラグメントに遅延読み込みを設定します。遅延読み込みとマークされたフラグメントは、実行時に必要な場合にのみレンダリングされます。大規模なフォームの読み込み時間が大幅に減少します。これは、繰り返し可能なパネルを使用したフラグメントでもサポートされます。詳しくは、遅延読み込みを設定を参照してください。

• レスポンシブグリッドレイアウトまたは最初のパネルには、フラグメントに遅延読み込みを設定しないでください。
• ファイル添付および利用条件コンポーネントは、遅延読み込みフラグメントではサポートされません。
• 遅延読み込みパネルの値がフォームの他の部分で使用されている場合、その値を「値をグローバルに使用」としてマークし、パネルがアンロードされたときにその値を使用できるようにします。
• 条件に基づいて表示または非表示する必要があるフラグメントに対して、表示ルールを記述することを検討します。

Apache Sling Main Servlet の​ リクエストあたりの呼び出し数 ​の値をかなり大きな値に設定します。これにより、Forms サーバーが追加の呼び出しを許可することができます。 この設定では、デフォルト値の 1500 が表示されます。 この値（1500 の呼び出し）は、Sites や Assets などの他の Experience Manager コンポーネントに対して使用されます。 アダプティブフォームのデフォルトの値セットは 20000 です。 ログで too many calls エラーが発生した場合、またはフォームのレンダリングに失敗した場合は、値を大きくして問題を解決してください。呼び出し数が 20000 を超える場合は、フォームが複雑であるという意味で、ブラウザーでフォームをレンダリングするのに時間がかかる場合があります。これは、フォームが初めて読み込まれたときにのみ発生し、フォームがキャッシュされた後は、パフォーマンスに大きな影響を与えません。

AEM Forms の事前入力サービスは、事前定義されたデータ XML ファイルからデータを読み取り、アダプティブフォームのフィールドに事前入力 XML ファイルの内容を事前入力します。

事前入力データ XML は、アダプティブフォームに関連付けられたフォームモデルのスキーマに準拠している必要があります。

事前入力 XML には「afBoundedData」および「afUnBoundedData」セクションを含めて、アダプティブフォームの連結されたフィールドと連結されていないフィールドのどちらにも事前入力するようにします。

フォームデータモデルに基づいたアダプティブフォームの場合、AEM Forms にはすぐに使用できるフォームデータモデルの事前入力サービスが用意されています。この事前入力サービスは、アダプティブフォーム内のデータモデルオブジェクトのデータソースに関するクエリを実行し、フォームのレンダリング時にフィールド値を事前入力します。

ファイル、crx、サービスまたは http プロトコルを使用して、アダプティブフォームに事前入力することもできます。

AEM Forms は、OSGi サービスとしてプラグインしてアダプティブフォームに事前入力できるカスタム事前入力サービスをサポートしています。

アダプティブフォームが基にしているフォームデータモデルに応じて、DoR 用のテンプレートを次のように設定できます。

• XFA フォームテンプレート：関連付けられた XDP ファイルを DoR テンプレートとして使用します。
• XSD スキーマ：アダプティブフォームで使用されているのと同じ XML スキーマを使用する、関連付けられた XFA テンプレートを使用します。
• なし：自動生成された DoR を使用します。

アダプティブフォームエディターの「レコードのドキュメント」タブから、ヘッダー、フッター、画像、色、フォントなどを直接設定します。

DoRService を使用して、DoR をプログラムにより生成します。

DoR から非表示フィールドを除外します。

afAcceptLang リクエストパラメーターを使用して、別のロケールで DoR を表示します。

複数のフォームに共通する要素に対してアダプティブフォームフラグメントを使用し、フラグメントをローカライズします。これにより、フラグメントを 1 回ローカライズするだけで、ローカライズされたフラグメントが使用されるすべてのフォームに反映されます。

新しいコンポーネントの追加や、ローカライズされたフォームへのスクリプトの適用などの変更は、自動的にはローカライズされません。したがって、ローカライズを何度も行わなければならない状況を避けるには、フォームをローカライズする前に完成させる必要があります。

ブラウザーのロケールを上書きし、指定したロケールでフォームをレンダリングするには、afAcceptLang 要求パラメーターを使用します。例えば、次の URL を使用すると、ブラウザー設定で指定されたロケールに関係なく、日本語ロケールでのフォームのレンダリングが強制されます。

https://'[server]:[port]'/<contextPath>/<formFolder>/<formName>.html?wcmmode=disabled&afAcceptLang=ja

現在、AEM Forms がサポートしているアダプティブフォームコンテンツのロケールは、英語（en）、スペイン語（es）、フランス語（fr）、イタリア語（it）、ドイツ語（de）、日本語（ja）、ブラジルポルトガル語（pt-BR）、中国語（zh-CN）、台湾中国語（zh-TW）、韓国語（ko-KR）です。ただし、実行時にアダプティブフォームに対する新しいロケールのサポートを追加できます。詳しくは、アダプティブフォームのローカライズに対する新しいロケールのサポートを参照してください。

Felix コンソールからの JavaScript および CSS の HTML クライアントライブラリ圧縮を有効にします。

すべてのクライアントライブラリを /etc.clientlibs/fd にキャッシュし、追加のカスタムクライアントライブラリを AEM ディスパッチャーにキャッシュすることで、発行したフォームの応答速度とセキュリティを向上させます。詳しくは、ディスパッチャーを参照してください。

/content/forms/af/ パス および /content/dam/formsanddocuments/* パスはキャッシュしないでください。アダプティブフォームのキャッシュ設定について詳しくは、アダプティブフォームのキャッシュを参照してください。

Web サーバー圧縮モジュールを経由して、HTML を有効にします。詳しくは、AEM Forms サーバーのパフォーマンス調整を参照してください。

大規模なフォームではリクエストあたりの呼び出し数の設定を増やします。大規模フォームおよび複雑なフォームのパフォーマンスの最適化を参照してください。

エラーハンドラーにより表示されるカスタムエラーページを作成します。

AEM Forms サーバーを保護します。

• nosamplecontent 実行モードを使用して、実稼働サーバーにサンプルコンテンツおよびサンプルユーザーがデプロイされていないことを確認します。AEM の実稼動準備完了モードでの実行を参照してください。

ヒープサイズを 8 GB 以上にします。その他の設定については、AEM Forms サーバーのパフォーマンス調整を参照してください。

サービスレベルのタスクを実行するには、管理者セッションではなくサービスユーザーセッションを使用します。詳しくは、サービス認証を参照してください。

ドラフトデータの保存：アダプティブフォームの「ドラフト」機能を使用している場合は、カスタムサービスプロバイダーインターフェイス（SPI）を実装して、データベースなどのより安全なストレージにドラフトデータを保存してください。詳しくは、「ドラフト&送信コンポーネントとデータベースの統合」を参照してください。

送信データの保存：「フォームポータル送信保存」を使用している場合は、カスタム SPI を実装してデータベースに送信データを保存してください。統合例については、ドラフト&送信コンポーネントとデータベースの統合の例 を参照してください。

安全なストレージにフォームデータと添付ファイルを保存するカスタム送信アクションを作成することもできます。詳しくは、アダプティブフォーム向けカスタム送信アクションの作成 を参照してください。

ドラフト ID の長さ：アダプティブフォームをドラフトとして保存すると、そのドラフトを一意に識別するためのドラフト ID が生成されます。ドラフト ID フィールドの長さの最小値は 26 文字です。アドビでは、ドラフト ID の長さを 26 文字以上に設定することをお勧めします。

Git などのバージョン管理をシームレスに使用：

• コンテンツからコードを分離することで、コンテンツ管理中の Git 競合が大幅に減少し、適切に整理されたリポジトリが促進されます。
• カスタム関数は、複数の投稿者が同時に作業するプロジェクトに価値があります。

技術的な利点：

• カスタム関数は、モジュール性とカプセル化を提供します。
• モジュールは、独立して開発、テスト、保守できます。
• コードの再利用性と保守性を向上させます。

効率的な開発プロセス：

• モジュール性により、開発者は特定の機能に専念できます。
• コードベース全体の複雑さを軽減して開発者の負担を軽減し、より効率的な開発プロセスを実現します。