ウィジェット ロジック

UI に追加のロジックを提供するには、イベントと入力制約という 2 つの方法があります。

イベント

イベントに応じてウィジェットのアクションを定義することで、より動的な UI にできます。たとえばボタン ウィジェットの onClick イベントは、クリックされたときのボタンの動作を決定します。

ほとんどのウィジェットに、少なくとも 3 つのイベント(onAttachonDetachonDataLoad)があります。一部のウィジェットには、その用途に関連した別のイベントがあります。たとえばテキスト フィールド ウィジェットには onValueChanged イベントがありますが、onClick イベントはありません。

プロパティ エディタの [Events] セクションを使用して、ウィジェットがイベントにどのように応答するかを定義します。イベント名の横にある矢印をクリックして、[Choose an Event] ダイアログを開きます。既製のスクリプトから 1 つを選択するか、[Custom Action] をクリックして独自のスクリプトを作成します。

イベント名 説明
onAttach ウィジェットが DOM に接続されたときにスクリプトを実行します。
例: アプリのメインパネルの onAttach イベントでは、ビューが読み込まれたときに状態を初期化するために、cookie を読み取ることができます。
onDetach ウィジェットが DOM から接続解除されたときにスクリプトを実行します。
例: アプリのメインパネルの onDetach イベントでは、ユーザーが離れたときにビューの現在の状態を保存するために、cookie に書き込むことができます。
onDataLoad ウィジェットとそのデータが読み込まれたときにスクリプトを実行します。
例: リスト ウィジェットの onDataLoad イベントでは、クエリの結果に基づいてパネルの特定の行を非表示にできます。
onClick ユーザーがウィジェットをクリックしたときにスクリプトを実行します。ボタン、リンク、その他のクリック可能なウィジェットで利用できます。
例: ボタンの onClick イベントでは、ユーザーを別のビューに移動させられます。
onValueChange ウィジェットの value プロパティが変更されたときにスクリプトを実行します。
例: テキスト フィールドの onValueChange イベントでは、ユーザーがクエリの入力を終了した後にフィールドのデータソースに対して検索を実施できます。
onValueEdit ユーザーがウィジェットの値を編集したときにスクリプトを実行します。onValueChange とは異なり、このイベントはバインディングやプログラムによる変更に応じて実行されることはありません。
例: テキスト フィールドの onValueEdit イベントでは、検索クエリに応じて一致する用語を強調表示できます。
onValidate ウィジェットの値が変更されたときや、別のスクリプトが検証をトリガーしたときにスクリプトを実行します。スクリプトは、新しい値がウィジェットの制約を満たす場合にのみ実行されます。
検証の注: 有効な値の場合、空の文字列、null、または undefined を返します。無効な値の場合は、エラー メッセージとともに空でない文字列を返します。

入力を検証する

多くの場合、ユーザー入力をデータベースに保存する前に検証すると便利です。たとえば、提供された電話番号の桁数が正しいことや、ユーザーの姓名フィールドが両方とも入力されていることがアプリで必須の場合があります。App Maker では、制約による入力の検証や、onValidate イベント時に実行される独自の検証スクリプトの記述ができます。

制約による検証

テキスト フィールド ウィジェットとテキストエリア ウィジェットのプロパティ エディタには、[Data Validation] セクションがあります。このような制約は、ウィジェットの値が変更されたときにトリガーされます。制約が満たされていない場合はエラーが表示されることがあります。制約は、明示的な値、データ バインディング、またはバインディング式を受け入れます。

プロパティ 説明
required 有効にすると、入力が必須であることが示されます。
minLength 空白を含む、文字列の最小許容文字数を定義します。先頭または末尾の空白は除きます。
maxLength 空白を含む、文字列の最大文字数を定義します。先頭または末尾の空白は除きます。
regexp ユーザー入力を検証する正規表現を定義します。JavaScript 正規表現ライブラリを使用します。
例: 米国の郵便番号形式に一致する正規表現「^\d{5}(-\d{4})?$」と入力します。

onValidate イベントによる検証

onValidate イベントを使用すると、独自の検証スクリプトを記述できます。次のような場合に最適です。

  • ウィジェットとフィールドの制約で対応できるユースケースよりも複雑な場合。
  • エラーカスタム メッセージを提供する必要がある場合。
  • 検証が他のフィールドやウィジェットの値に依存する場合。

onValidate イベントは、値が制約を満たした場合にのみトリガーされ、制約を処理します。

例: ホテル予約アプリでフロア番号に 1 から 21 の値を入力できるようにするが、13 は除く。

min length 制約を 1 に、max length 制約を 21 に設定し、ウィジェットの onValidate イベントで縁起の悪い数でないかチェックします。

      if (newValue == 13) {
        return "Please select a number with a bit more luck.";
      }
    

validate メソッドによる検証のトリガー

制約と onValidate スクリプトはウィジェットの値が変更されたときにのみトリガーされますが、これでは不十分な場合もあります。たとえば、すべてのフィールドが検証されるフォームがあり、ユーザーが 1 つのフィールドに入力せずに [送信] をクリックした場合、検証チェックが実行されない可能性があります。

このシナリオを回避するために、validate メソッドを使用して検証をトリガーできます。前述の例では、検証済みのフィールドと同じパネルにあると仮定して、送信ボタンの onClick イベントに次のコードを添付できます。

      if (widget.parent.validate()) {
        // We passed validation! Do whatever you want here...
      }
    

あるいは、各ウィジェットを明示的に検証することもできます。

      if (widget.parent.children.WidgetToValidate.validate()) {
        // We passed validation! Do whatever you want here...
      }
    

検証の優先順位

App Maker は次に示す順序でウィジェットを検証します。

  1. ウィジェットの制約:
    • 必須
    • 最大 / 最小の、長さ / 数
    • 正規表現
  2. onValidate イベント
  3. フィールド制約のような、バインドされたプロパティの制約

いずれかのステップで値が無効と判断されると検証はすぐに停止します。たとえば required 制約をチェックすると、制約チェックで値が検証に不合格となるため、onValidate イベントは null 値を受け取りません。

新しい値が検証に合格するまで、バインドされたプロパティは更新されません。validate() 呼び出しの結果として、初期チェックに不合格になった後にウィジェットが有効になった場合、その value プロパティを含むバインディングは適切に更新されます。