アダプティブフォームの数式

アダプティブフォームは、ダイナミックなスクリプト機能によってエンドユーザーのフォームへの入力作業を最適化および簡素化します。式を作成して、ダイナミックなフィールドやパネルの表示/非表示など、様々な動作を追加できます。 また、計算指標フィールドの追加、フィールドの読み取り専用化、検証ロジックの追加などを行うこともできます。 動的動作は、ユーザー入力や事前入力に基づいています。

アダプティブフォームの式言語はJavascriptです。すべての数式は有効なJavaScriptの数式で、アダプティブフォームのスクリプトモデルAPIを使用しています。これらの数式は、特定のタイプの値を返します。アダプティブフォームクラス、イベント、オブジェクト、パブリック API の完全なリストについては、「アダプティブフォームの JavaScript ライブラリ API リファレンス」を参照してください。

式を記述するためのベストプラクティス

• 式を記述したり、フィールドやパネルにアクセスしたりする場合は、フィールド名またはパネル名を使用します。フィールドの値にアクセスするには、valueプロパティを使用します。例：field1.value
• フォーム間でフィールド名およびパネル名には一意の名前を付けてください。式を記述する場合に使用されているフィールド名を使用すると競合を回避しやすくなります。
• 複数行にわたる式を記述する場合、セミコロンを使用して分を終了します。

繰り返しパネルを含む式のベストプラクティス

繰り返しパネルは、スクリプティングAPIまたは事前に入力されたデータを使用して追加または削除されたインスタンスのパネルです。繰り返しパネルの使用に関して詳しくは、繰り返し可能なセクションでのフォーム作成を参照してください。

• 繰り返しパネルを作成するためには、パネルダイアログで設定を開きます。そして最大カウントの値を1以上に設定します。

• 繰り返しパネル設定の最小カウントの値は、一つ以上設定することが可能ですが、最大値を超えてはなりません。

• 式が繰り返しパネルのフィールドを参照する場合、その式のフィールド名は一番近い繰り返し要素に解決されます。

• アダプティブフォームには、合計、カウント、最小値、最大値、フィルター等の繰り返しパネルの計算を簡素化するためのいくつかの特別な機能があります。全機能のリストについては、JavaScript ライブラリアダプティブフォームのAPI リファレンスを参照してください。

• 繰り返しパネルのインスタンスを操作するためのAPIは：

  • パネルインスタンスを追加するには：panel1.instanceManager.addInstance()
  • パネルの繰り返しのインデックスを取得するには：panel1.instanceIndex
  • パネルのinstanceManagerを取得するには：_panel1 or panel1.instanceManager
  • パネルのインスタンスを削除するには：_panel1.removeInstance(panel1.instanceIndex)

式のタイプ

アダプティブフォームでは、式を記述して、ダイナミックなフィールドやパネルの表示/非表示などの動作を追加できます。 また、式を記述して、計算指標フィールドを追加したり、フィールドを読み取り専用にしたり、検証ロジックを追加したりすることもできます。 アダプティブフォームは次の数式をサポートします:

• アクセス数式：フィールドを有効化/無効化します。
• 数式の計算：フィールドの値を自動計算します。
• 式:をクリックして、ボタンのクリックイベント上の操作を処理します。
• 初期化スクリプト：​フィールドの初期化で操作を実行します。
• オプション式：ドロップダウンリストを動的に埋めます。
• 要約式：アコーディオンのタイトルを動的に計算します。
• 検証数式：フィールドを検証します。
• 値コミットスクリプト：フィールド の値が変更された後にフォームのコンポーネントを変更します。
• 視認性の数式：フィールドおよびパネルの視認性をコントロールします。
• ステップ完了の式:ユーザがウィザードの次のステップに進むのを防ぐ。

アクセス式(イネーブルメント式)

アクセス式を使用してフィールドを有効/無効にできます。式がフィールドの値を使用する場合、フィールドの値が変更されるたびに、式がトリガされます。

適用性：​フィールド

​​戻り値の型 ：数式は、フィールドが有効/無効であることを表すブール値を返します。trueは​フィールドが有効であることを表し、falseは​フィールドが無効であることを表します。

例:field1の値を Xに設定した場合にのみフィールド を有効にするに は、次のアクセス式を使用します。 field1.value == "X"

数式の計算

数式の計算は、式を使ってフィールドの値を自動計算するのに使用されます。通常、この式には、他のフィールドの値プロパティを使用します。例えば、field2.value + field3.value のようになります。field2またはfield3の値が変更されると、式はトリガされ、値は再計算されます。

適用性：​フィールド

戻り値の型：数式は、式の結果が表示されるフィールドに対応する値を返します（例えば、小数値）。

例:field1内の2つのフィールドの合計を表示するcalculate式 は次 のとおりです。
field2.value + field3.value

クリック式

クリック式は、数式をクリック：ボタンのクリックイベント上で実行された操作を処理します。GuideBridgeは、送信や検証などのクリック式と共に使用される様々な機能を実行するためにAPIをデフォルトで提供します。APIの完全なリストについては、GuideBridge APIsを参照してください。

適任性：ボタンフィールド

戻り値の型：クリック式は値を返しません。数式が値を返した場合、その値は無視されます。

例:ボタンのクリック操作でテキストボックス textbox1 に値 ​​AEM Formsを入力するには、ボタンのクリック式を次のように指定します。 textbox1.value="AEM Forms"

初期化スクリプト

アダプティブフォームが初期化された場合に、初期化スクリプトがトリガされます。 シナリオに応じて、初期化スクリプトは次の方法で動作します。

• アダプティブフォームが、データの事前入力なしでレンダリングされた場合、初期化スクリプトは、フォームが初期化された後で実行されます。
• アダプティブフォームがデータの事前入力と共にレンダリングされる場合、スクリプトは事前入力操作が完了した後で実行されます。
• アダプティブフォームのサーバー側の再検証がトリガされた場合、初期化スクリプトが実行されます。

適用先：​フィールドおよびパネル

戻り値の型：​初期化スクリプトの数式は値を返しません。数式が値を返した場合、その値は無視されます。

例：データ の事前入力シナリオでは、値がnullとして保存された 'Adaptive Forms' ときにフィールドにデフォルト値を入力するため、初期化スクリプト式は次のようになります。
if(this.value==null) this.value='Adaptive Forms';

オプション式

オプション式はドロップダウンリストのフィールドをダイナミックに挿入するのに使用されます。

適用性：ドロップダウンリストのフィールド

戻り値の型：オプション式は文字列値の配列を返します。それぞれの値は​男性​または1=男性などの​キーと値のペアのような単純な文字列である場合があります。

例：別のフィールドの値に基づいてフィールドの値を入力するために、単純なオプション式を提供します。例えば、別のフィールドの結婚歴の式に基づいて​フィールドに子供の数を入力する場合、式はこのようになります。

marital_status.value == "married" ? ["1=One", "2=two"] : ["0=Zero"].

結婚歴フィールドの値が変わる場合は、常に式が再トリガされます。​ RESTサービスからドロップダウンを挿入することもできます。詳しくは、「ドロップダウンの動的な挿入」を参照してください。

要約式

要約式はアコーディオンレイアウトパネルの子パネルのタイトルを動的に計算します。要約式はルールで指定できます。タイトルはフォームフィールドまたはカスタムロジックを使用して評価されます。式は、フォームが起動すると実行されます。フォームの事前入力を行っている場合、式は、データが事前入力された後、または式で使用される依存フィールドの値が変更されたときに実行されます。

要約式は通常、アコーディオンレイアウトパネルの子の繰り返し処理に使用され、子パネルごとに意味のあるタイトルを作成します。

適用性：アコーディオンとして設定された パネルの直接の子であるパネル。

戻り値の型： 式は、アコーディオンのタイトルになる文字列型(String)を返します。

例： "アカウント番号："+ textbox1.value

数式の検証

数式の検証は、特定の数式を使ってフィールドを検証するのに使用されます。通常、このような式では、フィールドの値と共に正規式を使用してフィールドを検証します。 フィールドの値が変更されると、数式はトリガされ、フィールドの検証ステータスは再計算されます。

適用性：​フィールド

戻り値の型:式は、フィールドの検証ステータスを表すブール型(Boolean)の値を返します。値​false​はフィールドが無効であることを表し、true​はフィールドが有効であることを表します。
例：英国の郵便番号を表すフィールドの検証式は次の通りです：

(this.value && this.value.match(/^(GIR 0AA|[A-Z]{1,2}\d[A-Z0-9]? ?[0-9][A-Z]{2}\s*)$/i) == null) ? false : true

上記の例において、空でない値がパターンに一致しない場合は、数式は、そのフィールドが有効でないことを示すために falseを返します。

値コミットスクリプト

値コミットスクリプトがトリガされるのは、次のような場合です。

• ユーザーがUIからフィールドの値を変更した場合。
• 別のフィールドの値が変更されたため、フィールドの値がプログラムによって変更された場合。

適用先：​フィールド

戻り値の型：​値コミットスクリプトの数式は値を返しません。数式が値を返した場合、その値は無視されます。

例： commit上のフィールドに入力されたアルファベットを大文字を変換する場合に使用される値コミット式は次の通りです：this.value=this.value.toUpperCase()

表示式

表示式は、フィールド／パネルの視認性を制御するのに使用されます。通常、表示式にはフィールドの値プロパティが使用され、値が変更される度に再トリガされます。

適任性：フィールドおよびパネル

​​戻り値の型 ：数式は、フィールド/パネルが表示されているか否かを表すブール値を返します。falseフィールドまたはパネルが表示されないことを 表し、trueはフィールドまたはパネルが表示されていることを表します。

例：​フィールドの値が​​​男性に​設定された場合のみ表示されるパネルの​表示式は次の通りです：field1.value == "Male"1.

ステップ完了の式

ステップ完了の式は、ユーザーがウィザードの次のステップへ進むのを防ぎます。これらの数式は、パネルにウィザードのレイアウト（ワンステップずつ表示するマルチステップフォーム）がある場合に使用されます。ユーザーは、現在のセクションのすべての必須の値が入力され、有効な場合にのみ、次のステップ、パネルまたはサブセクションに移動できます。

適用性：ウィザードに設定された項目がレイアウトされたパネル

​​戻り値の型 ：数式は、既存のパネルが有効か無効かを表すブール値を返します。True​は既存のパネルが有効で、ユーザーが次のステップに移動できることを表します。

例：様々なパネルに表示されるフォームでは、次のパネルに移動する前に既存のパネルが検証されます。このような場合、ステップ完了の式を使用します。一般的に、これらの数式にはGuildBridge検証APIが使用されます。ステップ完了式の例を次に示します。
window.guideBridge.validate([],this.panel.navigationContext.currentItem.somExpression)

アダプティブフォームにおける検証

アダプティブフォームにフィールド検証を追加するには複数の方法があります。検証チェックがフィールドに追加された場合、True​はフィールドに入力された値が有効であることを示します。False は、値が無効であることを表します。フィールドの中または外にタブを付けた場合、エラーメッセージは生成されません。

フィールドに検証を追加する方法：

必須

コンポーネントの編集ダイアログにおいて、コンポーネントを必須にするには、TitleとText>Requiredのオプション​を選択します。​​また、適切な必須メッセージ(オプション)​も追加することができます。

検証パターン

フィールドにはデフォルトの検証パターンが複数あります。検証パターンを選択するには、コンポーネントの​編集​ダイアログで、​パターン​セクションを見つけて​パターンを選択します。パターンテキストボックスにおいて、独自のカスタム検証パターンを作成できます。​​検証ステータスは、入力されたデータが検証パターンに適応している場合のみTrue を返し、​それ以外の場合は​False​を返します。独自の検証パターンを書き込むには、「HTML5 フォームのパターン形式文字列サポート」を参照してください。

検証式

フィールドの検証は、別のフィールドの式を使って計算することもできます。この数式は、コンポーネントの編集ダイアログにあるスクリプトタブの検証スクリプトフィールドの中で作成されます。​​​​​フィールドの検証ステータスは、式が返す値によって異なります。 このような数式を作成する方法について詳しくは、「数式の検証」を参照してください。

追加情報

フィールドの表示形式の使用

表示形式は、異なる形式でデータを表示するのに使用されます。例えば、ハイフンが入った電話番号、郵便番号または日付選択を表示するのに、表示形式を使うことができます。表示形式は、コンポーネントの編集ダイアログにあるパターンセクションから​選択することができます。上記の検証パターンに類似したパターンをカスタムで作成することも可能です。

GuideBridge - APIとイベント

GuideBridgeは、ブラウザのメモリーモデルにおいてアダプティブフォームを操作するのに使うAPIが集まったものです。Guide Bridge API、クラスメソッド、公開されたイベントに関する詳細の紹介は、アダプティブフォームの JavaScript ライブラリ API リファレンスを参照してください。

様々な数式におけるGuideBridgeの使用方法

• フォームフィールドをリセットするには、ボタンのclick式でguideBridge.reset() APIをトリガーします。 同様に、送信APIはクリック式​guideBridge.submit()として呼び出すことができます。

• setFocus() APIを使用して、様々なフィールドやパネルにフォーカスを設定できます（パネルフォーカスは自動的に最初のフィールドに設定されます）。 setFocus()は、パネル間のナビゲーション、前/次のトラバーサル間の移動、特定のフィールドへのフォーカスの設定など、幅広いオプションを提供します。例えば、次のパネルに移動するには、次を使用できます。guideBridge.setFocus(this.panel.somExpression, 'nextItem').

• アダプティブフォームまたはその特定のパネルを検証するには、guideBridge.validate(errorList, somExpression).を使用します

数式外でのGuideBridgeの使用

GuideBridge　APIを数式の外で使用することもできます。例えば、アダプティブフォームをホストしているページHTMLとフォームモデル間の通信を設定するのにGuideBridge APIを使用することができます。さらに、フォームをホストするIframeの親から取得した値を設定できます。

GuideBridge APIを上記の例で使用するには、GuideBridgeのインスタンスを取得します。インスタンスを取得するには、windowオブジェクトのbridgeInitializeStartイベントをリッスンします。

window.addEventListener("bridgeInitializeStart", function(evnt) {

     // get hold of the guideBridge object

     var gb = evnt.detail.guideBridge;

     //wait for the completion of AF

     gb.connect(function (){

        //this function will be called after Adaptive Form is initialized

     })

})

フォームの初期化後(bridgeInitializeCompleteイベントがディスパッチされた後)にGuideBridgeを使用するには、window.guideBridgeを使用してGuideBridgeインスタンスを取得します。 APIを使って、guideBride.isConnectedGuideBridge初期化ステータスを確認することができます。

GuideBridgeイベント

またGuideBridgeは、ホストページ内の外部スクリプトのために特定のイベントも提供します。外部スクリプトは、これらのイベントを聞いて様々な操作を行います。例えば、フォームのユーザー名が変更される場合は、ページのヘッダー部分に表示される名前も常に変更されます。このようなイベントについて詳しくは、「アダプティブフォームのJavaScriptライブラリAPIリファレンス」を参照してください。

次のコードを使ってハンドラーを登録してください：

guideBridge.on("elementValueChanged", function (event, data)  {

      // execute some logic when value of a field is changed

});

フィールドのカスタムパターンの作成

前述のように、アダプティブフォームでは、作成者が検証または表示形式のパターンを提供することができます。デフォルトパターンの使用に加えて、アダプティブフォームコンポーネントに再利用可能なカスタムパターンを設定することも可能です。例えば、テキストフィールドや数値フィールドを定義できます。 設定が終われば、特定の種類のコンポーネントのすべてのフォームにおいてこれらのパターンを使用することができます。例えば、テキストフィールドのカスタムパターンを作成し、アダプティブフォームのテキストフィールドで使用することができます。 コンポーネントの編集ダイアログでパターンセクションにアクセスすることで、カスタムパターンを選択できます。パターン設定またはフォーマットに関する詳細は、「HTML5 のパターン形式文字列サポート」を参照してください。

特定のフィールドタイプのカスタムパターンを作成して、同じ種類のフィールドに再利用するには、次のステップを実行してください。

1. 自分のオーサーインスタンスで CRXDE Lite に移動します。

2. カスタムパターンを管理するためのフォルダーを作成します。アプリケーションディレクトリの下で、sling:folderタイプのノードを作成します。例えば、customPatternsという名前のノードを作成します。 このノードの下に、nt:unstructed型の別のノードを作成し、textboxpatternsという名前を付けます。 このノードには、追加しておくとよい様々なカスタムパターンが含まれています。

3. 作成したノードのプロパティタブを開きます。例えば、textboxpatternsのプロパティタブを開きます。このノードにプロパティguideComponentTypeを追加して、その値を​fd/af/components/formatter/guideTextBox​に設定します。

4. このプロパティの値は、パターンを設定するフィールドによって変わります。数値フィールドのguideComponentTypeプロパティの値は、 fd/af/components/formatter/guideNumericBoxです。日付選択フィールドの値は​fd/af/components/formatter/guideDatepickerです。
   "

5. ノードにプロパティを割り当てることでtextboxpatternsカスタムパターンを追加できます。名前追加を持つプロパティ（例：pattern1）を指定し、その値を追加するパターンに設定します。 例えば、Fax=text{99-999-9999999}の値を持つプロパティpattern1を追加します。 このパターンは、アダプティブFormsで使用するすべてのテキストボックスで使用できます。

   

   カスタムパターンの作成