データソース

App Maker ウィジェットとクライアント API はデータソースを経由してデータにアクセスします。データソースによって、以下の内容が決まります。

  • モデルでアプリケーションがデータにクエリを実行する方法
  • UI がこの情報にアクセスする方法

データソースには、データソース内で選択されているアイテムを示す item プロパティがあります。UI 上で、現在選択されているデータソース内のレコード情報をウィジェットで表示、編集するためには、item プロパティを使用します。また、このプロパティを使用することでクライアント スクリプトを使ったレコードへのアクセスや変更も可能です。

この記事では、以下について説明します。

  1. データソースの種類
  2. データソースのライフサイクル
  3. クエリのビルドや、その他のデータソース設定の構成方法を含む、クエリ データソースの作成方法
  4. クライアント スクリプトの利用によるクエリ データソースの調整方法
  5. リレーション データソースを利用して、関連付けされたレコードにアクセスする方法
  6. 作成モード データソースを使用して、ユーザー入力からドラフト レコードを作成する方法

データソースの種類

App Maker には 3 種類のデータソースがあります。

  1. クエリ データソース
  2. リレーション データソース
  3. 作成モード データソース

クエリ データソースには以下の情報が保存されます。

  • 単一のモデルに対するクエリの情報
  • 最後のクエリ実行で取得したレコードの情報

デフォルトでは各モデルに対して、対象のモデルと同名のクエリ データソースが作成されます。作成されたクエリ データソースをカスタマイズできるほか、モデル用のクエリ データソースをさらに作成することも可能です。フィルタ結果、異なるソート順、異なるページサイズなど、1 つのモデルで選択されるオプションを複数用意したい場合、多くのクエリ データソースが必要になる可能性があります。また、2 つの datasource.item 値を比較する際のように、同時に選択されている各レコード情報を保有したい場合、複数のデータソースが必要となる可能性があります。クエリの変更と再実行には、UI ウィジェットとクライアント サイド スクリプトを使用します。最後に実行したクエリ結果は、ウィジェットのプロパティにバインドされ、クライアント サイド スクリプトからアクセスされる場合があります。

UI の開発時には、通常はクエリ データソースをページや複合ウィジェットの最上位パネルに関連付けてください。そうすることにより、パネルにあるすべての子ウィジェットへ自動的にデータソースが継承され、データソース レコードにあるフィールド情報とウィジェットのプロパティを関連付けられるようになります。

リレーション データソースを使用すると、関連付けされたレコードのデータを表示できます。特定のリレーション エンドに対して、クエリ データソースや他のリレーション データソースから新たなリレーション データソースを作成します。リレーション データソースは、リレーション エンドにあるレコード情報を表示します。これらのレコード情報は、親データソースで現在選択されているレコードに関連付けられたレコード情報です。

リレーション データソースの一般的な用途は、マスターと詳細ビューの実装です。たとえば、お客様からの注文とそれに関連したアイテムを表示する UI をビルドできます。OrdersItems の 2 つのモデルを用意し、このモデル間で 1 対多となるようなリレーションを構築することになるでしょう。UI エディタでリレーション データソースを使用する方法の詳細については、UI へのデータバインドをご覧ください。

作成モード データソースにより、親クエリやリレーション データソースのアイテムが作成されます。

データソースのライフサイクル

データソースは、次の 4 つの状態のいずれかになります。

  1. Unloaded
  2. Unloaded + Loading
  3. Loaded
  4. Loaded + Loading

Unloaded 状態のデータソースは、データを一切保有していません。データソースのアイテムは空の配列になっており、その時点で選択中のアイテムは null です。Loading 状態のデータソースは、データの取得処理中のデータソースです。Loaded 状態のデータソースにはデータが格納されていますが、空のデータである場合があります。

データソースをいずれかの Loading 状態へと遷移させるためには、ロード処理の実行が必要です。ロード処理は次の場合に実行されます。

  1. デフォルトでは、データソースを使用するウィジェットがページにアタッチされた場合にロード処理が実行されます。ウィジェットのアタッチは通常、ユーザーがウィジェットの親ページを開いた場合に実行されます。
  2. デフォルトでは、データソースのデータ プロパティにバインディングするウィジェットがアタッチされた場合にロード処理が実行されます。たとえば、Orders ページに、Customers モデル内のフィールドにバインドされたラベル ウィジェットがある場合、Orders ページが表示される際に Customers データソースが読み込まれます。
  3. クライアント スクリプトによる datasourceloadloadPageprevPagenextPage の呼び出しによって読み込み処理が実行されます。

クエリ データソースでデータの自動読み込みを無効にして、このリストの最初にある 2 つの読み込み処理を抑制できます。データソースの unload メソッドを呼び出して、データソースの読み込みを解除できます。

クエリ データソースには、データソースが Loaded 状態に移行する際に実行される onLoad イベントがあります。onLoad イベントは、データソースにデータが読み込まれた後、スクリプトによるアクションを実行したい場合に役立ちます。たとえば、データが有効になったタイミングでウィジェットを表示するには、onLoad コードエディタに以下のスクリプトを入力します。

var widget = app.pages.MyPage.descendants.MyWidget;
widget.visible = true;

クエリ データソース

モデルを作成すると、自動的にクエリ データソースが作成されます。作成されたクエリ データソースをカスタマイズできるほか、モデル用のクエリ データソースをさらに作成することも可能です。

クエリ データソースを作成、編集するには:

  1. ナビゲーション パネルでモデルをクリックして、該当の [データソース] タブへ移動します。
  2. データソースを編集するには、該当のデータソースをクリックします。データソースを作成するには、[データソースを追加] をクリックします。
  3. データソースを構成します。変更は自動的に保存されます。

データソースには以下の構成オプションがあります。

クエリサーバー スクリプト

デフォルトでは、データソースによってモデルからすべてのレコードが読み込まれます。フィルタなど、サーバー側でカスタム ロジックを設定した場合に、クエリ スクリプトを使用してデフォルトのクエリ動作をオーバーライドできます。計算モデルに対しては、クエリ スクリプトを使用してデータソースのクエリ動作をすべて定義して、データソースにレコードを作成できます。

クエリ スクリプトの機能と要件:

  • クエリ スクリプト エディタからサーバー スクリプト関数を呼び出すことができます。これはクエリ スクリプトが長くなった場合に便利です。
  • カスタム パラメータを持つクエリ スクリプトに、クライアントからパラメータを渡すことができます。
  • クエリ スクリプトはデータソース モデルに属するレコードの配列を返す必要があります。

フィルタの例

たとえば、デフォルトの Employees データソース クエリは、Employees モデルにあるすべてのレコードを返します。たとえば、年齢が偶数で、クエリで指定する最低年齢を超える従業員のみを返したいとします。このクエリをデータソースに適用する場合は、以下のコードをクエリ スクリプト コードエディタに入力します。

var employeeResult = [];
// Modify passed query to also filter by minimum age.
query.filters.Age._greaterThan = 20;
var employeesAboveMinimumAge = query.run();
for (var i = 0; i < employeesAboveMinimumAge.length; i++) {
  if (employeesAboveMinimumAge[i].age % 2 == 0) {
    employeeResult.push(employeesAboveMinimumAge[i]);
  }
}
return employeeResult;

計算レコードの作成例

計算モデルを使うと、スクリプトの実行結果をレコードにして UI で使用できるようになります。たとえば、各地に何名の従業員がいるかを示すレコードを取得するために、Employees モデルに対して計算モデルを作成するクエリを実行します。データベースには EmployeesByLocation の実レコードがないので、クエリ スクリプトで newRecord() を呼び出し、レコードを作成する必要があります。次のスクリプトは、各地の従業員数を計算して、計算モデルに場所ごとのレコードを作成します。

var calculatedModelRecords = [];
var recordsByLocation = {};
var allEmployees = app.models.Employees.newQuery().run();
for (var i = 0; i < allEmployees.length; i++) {
  var employee = allEmployees[i];
  if (!recordsByLocation[employee.location]) {
    var calculatedModelRecord = app.models.EmployeesByLocation.newRecord();
    calculatedModelRecord.numberOfEmployees = 1;
    calculatedModelRecord.location = employee.location;
    calculatedModelRecords.push(calculatedModelRecord);
    recordsByLocation[employee.location] = calculatedModelRecord;
  } else {
    recordsByLocation[employee.location].numberOfEmployees++;
  }
}
return calculatedModelRecords;

カスタム パラメータ

クエリ スクリプトでは、データベースが提供できない種類のパラメータも使用できます。たとえば、ウェブサービスから取得した、会社の現在の株価に基づいてデータをフィルタできます。カスタム パラメータを持つサーバー上のクエリ スクリプトに、クライアントからパラメータを渡すことができます。

パラメータを追加するには:

  1. [データソース] タブで [パラメータを追加] をクリックします。
  2. パラメータの種類を選択します。
  3. パラメータの名前を入力します。

データソース クエリの parameters プロパティの下にあるパラメータにアクセスしてバインディングします。たとえば、バインディングを使ってテキスト フィールド ウィジェットの value プロパティをクエリ パラメータに結びつけることができます。

textField.value <-> datasource.query.parameters.MyParam

クエリ パラメータを利用して、クエリ スクリプトからパラメータにアクセスできます。以下のクエリ スクリプトを追加することで、これまでの例にこのアプローチを適用できます。以下のコードを追加すれば、ブール値のカスタム パラメータ RestrictAgetrue の場合にのみ最少年齢フィルタが付加されます。

// Modify query to also filter by minimum age if client enables the option.
if (query.parameters.RestrictAge) {
  query.filters.Age._greaterThan = 20;
}
var employees = query.run();

クエリビルダー

Cloud SQL データソース用にクエリビルダーを使用できます。これは MySQL WHERE 句の簡易版で、関連するモデルでのフィルタをサポートするほか、null に対応するクエリの作成を容易にします。アプリのユーザーから送信された情報に基づいて、複雑なクエリを実行する場合に、クエリビルダーが使用できます。

たとえば、さまざまな年金受給資格を持つ従業員を、ユーザーが HR データベースで検索できるようにするアプリを作成できます。クエリビルダーで、アプリのデータ検索に必要な論理式を作成することが可能です。この方法を使うと、ユーザー入力を解釈して Cloud SQL データベースでの検索に適用するカスタム スクリプトを作成しなくてもよくなります。なお、クエリビルダーでは、コードの補完機能もサポートされています(Ctrl+Space を押して実行します)。

ユーザー入力パラメータを使用してクエリを実装するには:

  1. クエリビルダーでクエリ式を作成し、ユーザー入力パラメータを用意します。
  2. ウィジェットのプロパティをユーザー入力パラメータにバインドします。

クエリの構築

クエリビルダーは次のルールに従ってクエリを処理します。

  • クエリ式は左から右に評価されます。
  • ユーザーによって入力されたパラメータは前に付くコロン(:)によって、モデル フィールドと区別されます。
  • or 演算子よりも and 演算子が優先して処理されます。
  • かっこ内のサブクエリは and および or 演算子よりも優先して処理されます。
  • "!" 演算子は式のブール値を否定します。
  • "?" 修飾子がリーフ演算子に使用されている場合、式の右側にある null 値が真であると見なされます。"?" 修飾子が使用された式は否定できません。

HR データベースのアプリの例の場合、指定された範囲の年齢に該当するか、指定日以降に仕事を始めた従業員を返す必要があります。クエリは次のようになります。

(Age >= :AgeMin and Age < :AgeMax) or StartDate > :StartDate
  • Age - アプリのモデルにあるフィールドです。各従業員の年齢情報が格納されています。アプリはユーザーに最少年齢(:AgeMin)と最高年齢(:AgeMax)の入力を求めます。このクエリは、その範囲に該当する従業員を返します。
  • コロン(:) - コロンにより、アプリの UI から取得するパラメータであることを示します。
  • かっこ - サブクエリを示します。App Maker は :StartDate より先にかっこ内のサブクエリを評価します。
  • and - 演算子です。両方の条件を満たす従業員を返すように、アプリへ指示します。
  • or - 演算子です。どちらかの条件を満たす従業員を返すように、アプリへ指示します。
  • StartDate - 従業員の就業開始日が格納されているフィールドです。ユーザーが :StartDate を入力すると、その日以降に仕事を開始した従業員をアプリが返します。

クエリ式の UI へのバインディング

先頭にコロンを付加してパラメータを式に追加すると、クエリビルダーが自動的にそれを認識し、クエリビルダーの下にある領域にクエリ パラメータを作成します。クエリ パラメータは、アプリのウィジェットにパラメータを結びつける際に使うデータ バインディング UI にも表示されます。

HR データベースのサンプルを使用するための手順は以下のとおりです。

  1. ウィジェット widgets を開き、テキスト ボックス text_fields を 2 つページに追加します。
  2. 次のようにして、テキスト ボックスの [] プロパティをバインディングします。
    • @datasource.query.parameters.AgeMin
    • @datasource.query.parameters.AgeMax
  3. 日付ボックス ウィジェット date_range をページに追加します。
  4. 次のようにして、日付ボックス ウィジェットの [] プロパティをバインディングします。
    • @datasource.query.parameters.StartDate
  5. 入力ウィジェットの [onValueChange] イベントを [データソースの再読み込み] に変更します。

その他のクエリビルダーの例

クエリ 戻り値
Age >= :AgeMin and Age <= :AgeMax and Active = :IsActive 最少年齢から最高年齢までの範囲に該当し、アクティブとなっている従業員すべて。
(Status = :Pending or Status = :Active) and Name startsWith :NamePrefix 保留中もしくはアクティブで、名前が NamePrefix で始まる従業員すべて。
!(Status = :Pending or Status = :Active) 保留中やアクティブではない従業員すべて。
Age >=? :AgeMin

クエリ パラメータの AgeMin が null の場合、すべての従業員が返されます。それ以外の場合は、最少年齢より年上の従業員が返されます。

この演算子は、クエリ パラメータの AgeMin を UI でバインディングする場合に役立ちます。たとえば、テキスト フィールドにクエリ パラメータ AgeMin をバインディングしていれば、初回はすべての従業員が返ります。ユーザーが AgeMin 値を入力すると、レコード情報がフィルタリングされます。ユーザーがテキスト フィールドをクリアすると、すべての従業員が再び表示されます。

クエリで >=? の代わりに >= 演算子を使用すると、初回やユーザーがテキスト フィールドをクリアした場合に従業員情報が返らなくなります。

Role notIn :Engineering or :Marketing

エンジニアやマーケティング担当ではない従業員すべて。

複数選択ウィジェット innotIn を使用することで、定義された複数のパラメータから 2 つ以上の項目をユーザーが選択できるようになります。

Computer startsWith :Chromebook and notContains :Pixel モデルに関係なく Chromebook Pixels 以外の Chromebooks を所有している従業員すべて。

計算 SQL 用の SQL クエリ

詳細については、計算 SQL モデルをご覧ください。

その他のクエリ データソース プロパティ

ページサイズ

ページサイズを設定して、1 回のクエリ実行に対してデータソースが返すレコード数を制御できます。そうすることで、クエリの実行結果として UI に返されるレコード数を制御し、パフォーマンスを向上させることができます。サーバーに 10,000 レコードのデータがある場合、一度にそのすべてを UI に読み込むと速度が低下し、管理も難しくなります。代わりに、ページサイズを設定して、データベースの nextPage メソッドを呼び出す [次へ] ボタンを作成します。

ページサイズをゼロに設定すると、すべてのレコードが表示されます。

ページサイズはデータソースのプロパティであるため、次のようなことができます。

  • ウィジェットのプロパティをバインディングする
  • クライアント側のスクリプトでページサイズにアクセスし、変更を行う

たとえば、スライダー ウィジェットの [value] プロパティをデータソースの [pageSize] プロパティにバインディングして、いくつのレコードを表示するかをユーザーに制御させることができます。

並べ替え

並べ替え可となっているフィールドであれば、レコードを昇順もしくは降順に並べ替えられます。複数フィールドの並べ替えには、クライアント クエリ スクリプトを使用します

手動保存モード

App Maker でデータソース アイテムの値が変更された場合、デフォルトでは、変更が自動ですぐにサーバーに保存されます。たとえば、テキスト フィールド ウィジェットの値をユーザーが変更した場合、新しい値が自動的にバインディング先のレコード フィールドに保存されます。

データソースを手動保存モードに設定することで、この自動保存動作を無効にできます。モデルエディタの [データソース] タブで、[手動保存モード] チェックボックスをオンにします。

手動保存モードでは、UI やスクリプトで明示的に変更を保存する必要があります。UI 上では、入力フィールドとフォームの動作が従来のウェブフォームのようになり、ユーザーの操作が必要になります。[保存] ボタンの onClick アクションに [データソースへの変更を保存] を設定し、ユーザーにクリックさせる必要があります。

クライアント側のスクリプトでは、チェンジ マネジメントに以下のメソッドを使用できます。

  • saveChanges - 現在の変更をサーバーに保存します。
  • clearChanges - 最後の saveChanges の呼び出し以降に発生したすべての変更を破棄します。
  • hasChanges - データソースに未保存の変更がある場合に true を返します。

データソースの itemitems プロパティを介したアクセスでレコードに発生した変更(リレーション関連のプロパティを介したアクセスによるレコードへの変更も含む)は、クライアントのローカルに格納され、保存やロールバックが可能です。

データを自動で読み込む

デフォルト動作として、ウィジェットがデータソース上のデータにバインディングされている場合は、データソースが常に自動的にデータを読み込みます。[データを自動的に読み込む] チェックボックスをオフにすると、loadloadPagenextPageprevPage メソッドが呼び出された場合にのみデータソースがデータを読み込むようになります。

データ読み込みの前に、ユーザーにクエリフィルタの値を設定させたい場合は、データの読み込みを遅らせてください。

onLoad アクション

データソースの読み込みに応じてクライアント側のスクリプトを実行するには、コードボックスにスクリプトを入力します。onLoad アクションは、クエリの実行結果がサーバーからクライアントに返されるたびに実行されます。読み込みの詳細については、データソースのライフサイクルをご覧ください。

アイテム変更時のアクション

現在のアイテムが変更されるたびにクライアント側のスクリプトを実行するには、コードボックスにスクリプトを入力します。

現在のアイテムは、次の理由により変更される可能性があります:

  • データソースがデータを再読み込みし、返されたデータの中に現在のアイテムが存在しなかった場合。
  • クライアント側スクリプトによって、データソースの next メソッドや prev メソッドが呼び出された場合。
  • クライアント側スクリプトやバインディングによって、データソースの item プロパティに値が割り当てられた場合。
  • クライアント側スクリプトによって、データソースの selectIndex メソッドや selectKey メソッドが呼び出された場合。
  • 一部のウィジェットにより、データソースの現在のアイテムが自動的に変更された場合。たとえば、リスト ウィジェットでユーザーが行のクリックを行い、データソースの現在のアイテムが変更された場合など。

プリフェッチ

プリフェッチは、UI やクライアント スクリプトで使用する関連レコードをリレーション エンドから効率的に読み込むために使用されます。他のリレーション エンドの関連レコードは自動的に読み込まれないため、クライアント スクリプトでリレーションのレコードを使用する場合は、関連レコードをサーバーから明示的に読み込む必要があります。関連レコードを読み込む方法の 1 つとして、プリフェッチの有効化があります。有効化することで、App Maker がクエリの実行結果を読み込む際に関連レコードが読み込まれるようになります。

データソースに多数のレコードがあり、そのすべてに対して関連レコードを読み込む必要がある場合、プリフェッチを使用することで、UI のパフォーマンスが向上する可能性があります。たとえば、自身に対して ManagerTeamMembers という 2 つのリレーション エンドがある Manager リレーションを持った Employees モデルがある場合、UI には、クエリ データソースに基づく Employees のレコード一覧と各従業員の Manager が表示されます。

プリフェッチを行わない場合、App Maker はデータソースにある各従業員のレコードと関連するマネージャーのレコードを求めます。サーバーに対する多数のリクエスト送信が必要となるため、この処理は遅くなる可能性があります。プリフェッチが有効な場合、App Maker がクエリの実行結果とともに関連レコードを読み込むので、初回読み込み後の UI の動作が高速になります。

関連レコードをクライアントに読み込ませる他の方法については、クライアント スクリプトで関連付けを変更するをご覧ください。

クライアントでデータソース クエリを調整する

クエリ データソースには、クライアント スクリプトでクエリを変更する際に使用できるプロパティとメソッドがあります。クエリ オブジェクトは、データソースが読み込まれた場合に、サーバーに送信されるクエリを表します。このオブジェクトには、クエリの条件と、返り値とする実行結果のページを指定するプロパティがあります。

クエリ データソースで読み込みを発生させた場合:

  1. クエリ データソースは、現在のクエリをサーバーに送信します。
  2. クエリ データソースは、クエリの実行結果でデータを更新します。
  3. クライアント上のレコードも、クエリの実行結果で更新されます。

クエリの実行結果でレコード情報に変更がなくても、クエリ データソースを読み込んだ場合に、クライアント上でレコード値の変更が発生する場合があります。これは、サーバー側のスクリプトまたは他のクライアントによってレコードが変更された場合に発生する現象です。

フィルタ

クエリ オブジェクトの filters プロパティには、モデルのフィールドに対するクエリ条件が保持されます。フィルタは、次の構文で指定します。

datasource.query.filters.field-id.filter-operator = value

ここで:

  • field-id はフィルタリングで使用できるモデル内のフィールドです。
  • filter-operatorequalscontains などのフィルタ アクションです。サポートされるフィルタ演算子は、フィールドの型とデータベースによって異なります。フィルタ演算子の詳細については、クライアント API クエリのドキュメントをご覧ください。
  • value はクエリ内のフィールドと演算子で使用されるパラメータです。in 演算子と notIn 演算子を使用する場合を除いて、値の型とフィールドの型を一致させる必要があります。in 演算子と notIn 演算子を使用する場合、そのパラメータ値はフィールド型の配列でなければなりません。

リスト フィールドの場合、リストにある 1 つ以上のアイテムがクエリフィルタに一致する必要があります。複数の値を filters のプロパティに割り当てる場合、読み込まれるレコードはすべてのフィルタに一致する必要があります。

Cloud SQL モデル データソースのクエリ オブジェクトには、リレーション フィルタに関するプロパティもあります。これらのプロパティによって、関連レコードやそのフィールド、またはキーによるレコードのフィルタリングが可能になります。フィルタリングは、1 対 1 および多対 1 の関係に対してのみサポートされます。

クライアント クエリの例:

  • 単一フィルタ - 次のコードは、ウィジェットのデータソースに、"John Smith" という名前が入ったレコードを返すクエリフィルタを追加します。

    var datasource = widget.datasource;
    datasource.query.filters.Name._equals = 'John Smith';

  • 複数のフィルタ - 次のコードは、年齢が 18 歳より上で、名前が "John" で始まるレコードに一致する、複数のクエリフィルタを追加します。

    var datasource = widget.datasource;
    datasource.query.filters.Name._startsWith = 'John';
    datasource.query.filters.Age._greaterThan = 18;

  • リスト フィールドの一致 - 以下のクエリは、次のレコードを読み込みます。record.Emails = ['smith.j@example.com', 'john@example.com'] これは、Emails リスト フィールドにあるアイテムの 1 つが john@ で始まるためです:

    datasource.query.filters.Emails._startsWith = 'john@';

  • in 演算子 - 次のコードは、クエリフィルタで in 演算子を使い、favoriteColor フィールドの値が blue または green のレコードを読み込みます。

    var datasource = widget.datasource;
    var colors = ['blue', 'green'];
    datasource.query.filters.FavoriteColor._in = colors;

  • リレーション フィールド フィルタ - Employee モデルが、自身とマネージャー、チームメンバーとで表される 1 対多の関係を持つ場合、次のことが可能です。

    • manager1 に割り当てられているチームメンバーのレコードを読み込む:

      var datasource = widget.datasource;
      datasource.query.filters.Manager._equals = 'manager1';

    • マネージャーのレコードキーでフィルタする:

      datasource.query.filters.Manager._key._in = ['manager1RecordKey', 'manager2RecordKey'];

    • マネージャーのマネージャー名でフィルタする:

      datasource.query.filters.Manager.Manager.Name._equals = 'John Doe';

    他のフィールド フィルタと同様に、リレーション フィルタのプロパティの値を null に設定した場合、フィルタは適用されません。

並べ替え

データソース用に構成されている並べ替えを、クライアント スクリプトでオーバーライドできます。データソースのモデルで並べ替え可となっている 1 つ以上のフィールドでデータを並べ替えます。Cloud SQL モデル データソースの場合、リレーション エンドが 1 対 1 または 1 対多であれば、関連レコードのフィールドによる並べ替えも可能です。たとえば、という多対 1 の関係の場合、市を州ごとに並べ替えられます。

詳細については、クエリの並べ替えプロパティをご覧ください。

ページ インデックス

ページ インデックス プロパティは、読み込むページの番号を指定します。デフォルトでは、クエリ実行結果の 1 ページ目が読み込まれます。このプロパティは、任意の正の数値に変更できます。次回のクエリ データソースが読み込まれた場合に、そのページ番号のレコードが読み込まれます。

ページサイズ

ページサイズ プロパティは、1 回のクエリ実行に対してサーバーが返すレコードの数を指定します。

リレーション データソース

リレーション データソースを使用すると、リレーション エンドのデータソースにあり他のレコードと関連するレコードを簡単に表示できます。

プロパティ エディタにあるウィジェット用にリレーション データソースを設定できます。データソース ダイアログには、親モデルに対して構成された各リレーションのリレーション データソースが表示されます。リレーション データソースを UI で選択する方法については、UI へのデータ バインディングで確認できます。データモデルを接続するのチュートリアルにある例を確認してください。

関連レコードを読み込む

リレーション データソースが構成されているウィジェットが読み込まれると、現在のレコードに関連するレコードが自動的に読み込まれます。リレーション データソースの読み込みを発生させると、関連レコードも読み込まれます。

多くの場合において、アプリがデータを使用する前に、関連レコードが確実に読み込まれているようにする必要があります。レコードの関連付けが読み込まれた場合に通知を受け取ったり、スクリプトを実行するには、ウィジェットの onDataLoaded イベントを使用します。アプリで関連レコードを使用する一般的な方法は次のとおりです。

  1. 関連データの読み込みを確実にするために、リレーション データソースを使用する非表示のパネルを作成します。
  2. 作成した非表示パネルの onDataLoaded イベントを使用して、関連データを使用したロジック処理を実行します。

関連レコードをサーバーから再度読み込むには、リレーション データソースの load を呼び出します。クライアント側のスクリプトやバインディングによる変更ではなく、サーバー スクリプトによって関連レコードが変更された際に、再読み込みが必要となる場合があります。

現在のレコードにある _reload メソッドを使うことでも、関連データの再読み込みができます。

作成モード データソース

作成モード データソースを使って、親のクエリ データソースやリレーション データソースにアイテムを作成できます。これらのアイテムはデータベースに自動保存されません。代わりに、ユーザーによるレコード保存のアクションが発生するまで、データはクライアントのドラフト レコードに格納されます。ドラフト レコードでは、新しいレコードのテンプレートも提供されています。作成モード データソースは、その親にあたるデータソースと同じモデルに属します。

作成モード データソースでは:

  • UI 要素を、作成モード データソース内のフィールドにバインディングできます。これらのフィールドからドラフト レコードに値が格納されます。
  • データソース レコードにデフォルトのフィールド値を設定できます。このアプローチでは、必須のフィールドには常に値が入ります。作成モード データソースによってデータベースにレコードが保存されると、フィールド値はデフォルト値にリセットされます。デフォルト値は UI やスクリプトで設定できます。

アプリの UI とクライアント スクリプトを使用して、作成モード データソースを操作できます。

フォームを使ってレコードを作成する

入力型フォームの値は、作成モード データソースのフィールドにデフォルトでバインディングされます。ユーザーがフォームに入力すると、App Maker がその値をドラフト レコードに保存します。作成モード データソースは @datasource.parent-datasource.modes.create で、UI により parent-datasource (create) としてレポートされます。フォームの各フィールドは、ドラフト レコードのフィールドと対応する datasource.item.field にバインディングされます。

ユーザーがフォームに入力すると、ユーザーが [送信] ボタンを押すまでの間、クライアントにレコードが保存されます。[送信] ボタンの onClick アクションとなっている datasource.item.createItem() でアイテムが作成され、親データソースに追加されます。[クリア] ボタンの onClick アクションとなっている widget.datasource.clearChanges() で作成されたデータソースのレコードを消去します。

データ ウィジェット: フォームデータの処理を行うで詳細をご確認ください。

スクリプトを使ってレコードを作成する

クライアント スクリプトを使って、作成モード データソースにレコードを追加できます。次のような場合に、この方法を使用してレコードを追加してください。

  • ユーザー名とレコード作成日などのセッション データを自動的に追加したい場合
  • レコードの作成前に、データソースのフィールドと対応するように名前の姓と名を連結するなどして、フォームのデータを処理したい場合

たとえば、DateAdded フィールドを持つ People モデルがある場合、作成モード データソースの DateAdded プロパティに new Date(); を設定すると、そのデータソースを介して作成されたレコードに、開始時の日付としてユーザーのタイムゾーンにおける現在の日付が保持されるようになります。

var createDatasource = app.datasources.people.modes.create;
var draft = createDatasource.item;
draft.DateAdded = new Date();
createDatasource.createItem(function(createdRecord) {
 alert('Created record on ' + createdRecord.DateAdded)
});

詳細については、CreateDataSource をご覧ください。