以下の各セクションでは、Start 式を使用する方法を説明します。
- テンプレートで Start 式を使用してレコードのリストを表示する
- 親レコードと祖父母レコードの列にアクセスする
- 一般的な Start 式
- レコードの順序をコントロールする
- 表示するレコード数をコントロールする
- Start 式と End 式をトラブルシューティングする
Start 式は <p> または見出し要素内に置く必要があります。テンプレートで Start 式を使用してレコードのリストを表示する
Start 式はレコードのリストを表示するためにテンプレートで使用されます。テンプレートの最初に置かれる Start 式は、どのレコードを表示するかをコントロールします。その後、テンプレートを使用して各レコードの書式設定を行います。
各テンプレートは、<<Start:Start 式>> で始まり <<End>> で終わります。コロンに続く Start 式により、テンプレートを使用して書式設定するレコードのリストが生成されます。より具体的には、Start 式はテンプレートを使用して書式設定するテーブル行のキー値のリストを生成します。
テンプレートには 1 つ以上の埋め込みテンプレートが含まれる場合があります。あるテンプレートを別のテンプレートに埋め込むことで、レコードの階層を表示できます。たとえば、次の方法で、Customers、Orders、Order Details レコードを 3 階層で表示できます。
Customers用のテンプレートを作成します。Customers用テンプレート内にOrders用の埋め込みテンプレートを作成します。Orders用テンプレート内にOrder Details用の埋め込みテンプレートを作成します。
Start 式を含む埋め込みテンプレートは、次のユースケースで使用されます。
- データ変更 bot の埋め込み式
データ変更 bot は、テーブル内の特定のレコードが変更されると呼び出されます。たとえば、Ordersテーブルに関連付けられたデータ変更 bot は、ある注文が変更されるとトリガーされます。テンプレートは、変更されたレコードのコンテキストで評価されます。テンプレートでは、Ordersレコードの詳細とOrdersレコードに関連付けられたOrder Detailsレコードの両方を表示できます。Order Detailsレコードを表示するには、テンプレートにStart式を含む埋め込みテンプレートが含まれている必要があります。 - スケジュール設定された bot のトップ階層の式
スケジュール設定された bot では、一連のレコードを表示できます。たとえば、すべてのOrdersやすべての未処理のOrdersを表示できます。Ordersレコードを表示するには、テンプレートにStart式を含む埋め込みテンプレートが含まれている必要があります。 - スケジュール設定された bot の埋め込み式
スケジュール設定された bot では、レコードの階層を表示できます。たとえば、すべての未処理のOrdersレコードを関連するOrder Detailsレコードとともに表示できます。Ordersレコードを表示するには、テンプレートにStart式を含む埋め込みテンプレートが含まれている必要があります。その後、Orders用テンプレート内にOrder Details用の埋め込みテンプレートを作成します。
例
Orders レコードが更新されるときにデータ変更 bot で使用されるこのテンプレートについて考えてみましょう。このテンプレートには、更新された Orders レコードのすべての Order Details レコードを表示する埋め込みテンプレートが含まれています。
埋め込みテンプレートには、次の Start 式が含まれています。
<<Start:[Related Order Details]>>
Start 式は、この式を含むテンプレートのコンテキストで評価されることに留意することが重要です。この場合、外側のテンプレートは Orders レコードの書式設定をするために使用されるので、Start 式はその Orders レコードのコンテキストで評価されます。そのため、Start 式は現在の Orders レコードの列を利用できます。
対照的に、<<Start>> と <<End>> の間の Start 式以外の式は、各子レコードのコンテキストで評価されます。この例では、Start 式は Order Details レコードを参照するため、<<Start>> と <<End>> の間の式は子である Order Details レコードのコンテキストで評価されます。<<Start>> と <<End>> の間の式は、通常 Order Details レコードの列を参照します。
埋め込みテンプレートは、Start 式によって返される子レコードごとに 1 回評価されます。たとえば、子である Order Details レコードが 5 つある場合、埋め込みテンプレートは 5 回評価されます。
親レコードと祖父母レコードの列にアクセスする
埋め込みテンプレート内では、外側階層のテンプレートのテーブルの列を参照できます。たとえば、Customer レコード、埋め込まれた子の Order レコード、さらに埋め込まれた孫の Order Detail レコードで構成される 3 階層構造のテンプレートの場合です。
親レコードの列にアクセスする
埋め込まれた Order Detail テンプレートでは、次の形式で式の逆参照を指定して、親である Order レコードの列を参照します。
[_THISROW-1].[親レコードの列名]
たとえば、[_THISROW-1].[Order Date] は親である Order レコードの Order Date 列の値を取得します。
注: [_THISROW-n] 文字列には空白を埋め込むことはできません。値 n は定数の数値になります。式にすることはできません。
祖父母レコードの列にアクセスする
埋め込まれた Order Detail テンプレートでは、次の形式で式の逆参照を指定して、祖父母である Customer レコードの列を参照します。
[_THISROW-2].[祖父母レコードの列名]
たとえば、[_THISROW-2].[Phone] は祖父母である Customer レコードの Phone 列の値を取得します。
[_THISROW] => トップ階層
[_THISROW-1] => 1 階層さかのぼって親を参照
[_THISROW-2] => 2 階層さかのぼって祖父母を参照
[_THISROW-3] => 3 階層さかのぼって曽祖父母を参照
[_THISROW-n] => n 階層さかのぼる
一般的な Start 式
Start 式にはいくつかの形式があります。以下に一般的な例を示します。
テーブル全体
最もシンプルな Start 式は、テーブルの名前とそのキー列です。
<<Start:Orders[Order Id]>>
この形式の Start 式は通常、スケジュール設定された bot のトップ階層の Start 式としてのみ意味を持ちます。
逆参照
一般的な Start 式は、逆参照の仮想列の名前です。以下に例を示します。
<<Start:[Related Order Details]>>
Orders レコードには、逆参照の仮想列 Related Order Details が含まれています。この仮想列は、Orders テーブルから子である Order Details テーブルへの逆参照を含めるために、AppSheet によって自動的に追加されたものです。これには、関連する子である Order Details レコードのキー値のリストが含まれます。上の例では、列名 Related Order Details を角括弧で囲む必要があります。
条件付き逆参照
もう一つの一般的な Start 式は、参照されるレコードのサブセットを選択する逆参照の仮想列の名前です。これは、SELECT 式で逆参照を囲むことで実現できます。以下に例を示します。
<<Start:SELECT([Related Order Details][OrderDetail Id], [Order Status] = "Open")>>
Orders レコードには、逆参照の仮想列 Related Order Details が含まれています。上の例では、列名 Related Order Details を角括弧で囲む必要があります。
この仮想列は、Orders テーブルから子である Order Details テーブルへの逆参照を含めるために、AppSheet によって自動的に追加されたものです。これには、関連する子である Order Details レコードのキー値のリストが含まれます。AppSheet では当初、この列には Related Order Details [Order Id] という名前が付けられていました。この例では、SELECT 式で使用するために列の名前を Related Order Details に変更する必要がありました。これは、元の AppSheet で生成された名前である [Order Id] は角括弧で囲まれていることから、式が機能しなくなるためです。
Start 式の SELECT は常にキー値のリストを返す必要があるため、SELECT 式の最初の引数は [Related Order Details][OrderDetail Id] になります。値 [Related Order Details] は、逆参照列の名前です。値 [OrderDetail Id] は、Order Details テーブルのキー列の名前です。まとめると、最初の引数は、参照されているすべての Order Details レコードのキーを返します。
SELECT 式の 2 番目の引数には、Order Status が Open である参照された Order Details レコードのみが含まれます。
SELECT 式
表示したい子レコードのキー値を生成する SELECT 式を指定することで、子レコードのサブセットを表示できます。
<<Start: SELECT(Orders[Order Id], AND(IN([Order Id],[_THISROW].[Related Orders]), [Order Status] = "Open"))>>
SELECT 式はキー値のリストを生成する必要があります。この例では、Order Id 列が Orders テーブルのキーです。
レコードの順序をコントロールする
OrderBy を使用して、レコードの表示順序をコントロールできます。
OrderBy() 関数のパラメータは、OrderBy(レコードのリスト, 並べ替えの基準列, 降順並び替え) です。
次の Start 式を使用すると、Order Details レコードを価格が最も高いものから最も安いものの順に表示できます。Total 列には各 Order Details レコードの合計値が含まれます。
<<Start:OrderBy([Related Order Details], [Total], FALSE)>>
次の Start 式を使用すると、「未処理」の Orders レコードを Order Date 順に表示できます。
<<Start:OrderBy(SELECT(Orders[Order Id], [Order Status]="Open"),[Order Date],TRUE)>>
次の Start 式を使用すると、「未処理」の Orders レコードを Order Date の逆順に表示できます。
<<Start:OrderBy(SELECT(Orders[Order Id], [Order Status]="Open"),[Order Date],FALSE)>>
表示するレコード数をコントロールする
Top 関数を使用すると、表示するレコードの最大数を制限できます。
Top 関数のパラメータは、Top(並び替え済みレコードリスト, レコードの最大数) です。
注: Top は、OrderBy とのみ機能し、単独では使用できません。
次のようにして最大 3 つのレコードを表示します。
<<Start:Top(OrderBy([Related Orders], [Order Date]), 3)>>
この Start 式を使用して、最新の「未処理」の Orders レコードを表示します。<<Start:Top(OrderBy(SELECT(Orders[Order Id], [Order Status]="Open"),[Order Date],TRUE),1)>>
この Start 式を使用して、最も古い「未処理」の Orders レコードを表示します。<<Start:Top(OrderBy(SELECT(Orders[Order Id], [Order Status]="Open"),[Order Date],FALSE),1)>>
Start 式と End 式をトラブルシューティングする
以下に、一般的なエラー メッセージとその対処方法を示します。
Incomplete Start expression
Start 式にエラーがあり、表示されるエラー メッセージに Start 式の一部のみが含まれている場合は、Start 式に埋め込まれた改行が含まれていないことを確認します。埋め込まれた改行は、式パーサーの混乱の原因となります。これは、Start 式が表のセルに含まれている場合に特によく発生します。この場合、Start 式に誤って改行を入力してしまうことが多々あります。
Found 1 unmatched 'End'
エラー メッセージ Found 1 unmatched 'End' は、式パーサーが End 式を見つけたものの、それに対応する Start 式を見つけられなかったことを示しています。
Start 式に埋め込まれた改行が含まれていないことを確認します。埋め込まれた改行は、式パーサーの混乱の原因となります。これは、Start 式が表のセルに含まれている場合に特によく発生します。この場合、Start 式に誤って改行を入力してしまうことが多々あります。たとえば、Start 式内、<< と Start の間、Start: の後、終わりの >> の前に改行が挿入されていることがあります。
Found 1 unmatched 'Start'
エラー メッセージ Found 1 unmatched 'Start' は、式パーサーが Start 式を見つけたものの、それに対応する End 式を見つけられなかったことを示しています。
End 式に埋め込まれた改行が含まれていないことを確認します。埋め込まれた改行は、式パーサーの混乱の原因となります。これは、End 式が表のセルに含まれている場合に特によく発生します。この場合、End 式に誤って改行を入力してしまうことが多々あります。たとえば、<< と End の間、End と >> 間に改行が挿入されていることがあります。
Found n '<<' values but m '>>' values
すべての Start 式と End 式が << で始まり、>> で終わっていることを確認します。