マークアップページの記法

マークアップページのコードの文法と、よく使う組み立て方を説明します。要素ごとの属性は、要素一覧を参照してください。

書き方の規則

コードは、HTML に似たタグで要素を書きます。書けるタグと属性は、要素一覧にあるものだけです。HTML のタグ、CSS、class、style は書けません。

<Columns>
  <SqlView id="…" page="…" sql="…">
    <Card title="今月の売上">
      <Text size="2xl" weight="bold">{{ row.sales }}</Text>
    </Card>
  </SqlView>
  <Chart id="…" page="…" chart="…" />
</Columns>

• タグ名と属性名は、大文字と小文字を区別します
• すべての要素を閉じます。子を持たない要素は /> で閉じます
• 属性の値は " で囲みます。値に " を含むときは ' で囲みます
• 真偽値の属性は、値なしで書くと真になります（<Collapse open>）
• 本文の < は < と書きます。{{ … }} の中には、< をそのまま書けます
• 本文の空白と改行は、HTML と同じく 1 つの空白にまとめられます。改行するときは <Br /> を書きます
• Markdown は解釈されません。太字や色は <Span>、箇条書きは <List> で書きます
• <!-- … --> はコメントです。{{ を文字として書くときは、\{{ と書きます

解釈が曖昧な書き方は、推測で補われず、エラーになります。

コードの構造

要素ごとに、どの要素の中に書けるか（親）と、中に何を書けるか（子）が決まっています。要素のリファレンスの「構造」の表で確認できます。

構造上の区分

区分	内容
block	ページに並べる要素（<Text>・<Card>・<Chart> など）。ページの直下と、子に block を取る要素の中に書く
inline	文の中に書く要素（<Span>・<Link> など）。<Text> の中に書く
text・expr	文字と {{ … }}。<Text>・<Heading> など、文字を表示する要素の中に書く
control	出し分けと繰り返し（<If>・<For> など）。条件と繰り返しを参照
―	決まった親の中にだけ書く要素（<ListItem>・<Tab> など）

<Card> や <TableCell> の中に文字を書くときは、<Text> で囲みます。

要素の ID

<Chart>・<SqlView>・<Heading>・<Image> など、実行結果・画像・リンクに関連付けられる要素には、id を書きます。id が必要な要素は、属性の表で確認できます。

• 形式は ObjectId（16 進数 24 文字）で、ページの中で重複しないようにします
  • cdm notebook format で、不足している id が補われます。自分で書くときは、cdm util gen-id などで生成した値を使います
  • 要素をコピーしたときや、同じチャートを 2 か所に置くときは、別の id にします
• 実行結果と画像は id に関連付けられるため、要素を移動しても保持されます。id を書き換えると、別の要素として扱われます
• <SqlView> の中の要素には、id を書けません

式

本文や属性の値に、{{ … }} で式を書きます。パラメータの値や SQL の結果を、文字・条件・見た目に使えます。

書ける場所

式の書き方は、書く場所によって 2 通りあります。どちらで書くかは、属性の表の値の欄（「式：単一式」「式：文字＋式」）で確認できます。

• 文字＋式：文字の中に、値を文字列に変換して差し込みます（title="{{ r.segment }} の解約"）。本文と、title など見出しや説明の属性に書けます
• 単一式：値全体を 1 つの {{ … }} にします（condition="{{ row.mom < 0 }}"）。条件・数値・色など、型が決まった属性に書けます。値の欄が「式（…）」の属性も単一式です

書ける式

• リテラル：文字列（'…' か "…"）、数値、true、false、null
• 演算子：== != < <= > >= in && || ! c ? a : b、数値の + - * /、括弧 ( )
• 関数：size()・formatNumber()・formatDate() など（式の関数）

集計など、ここにない計算は、SQL で列として用意します。属性の値の式で文字列を書くときは、属性を囲む引用符と別の引用符を使います（condition="{{ row.region == 'East' }}"）。

式から参照できる値

書き方	内容	参照できる場所
param_<パラメータの ID>	パラメータの値	どこでも
view.<名前>	表示の状態（表示の状態）	どこでも
env.<名前>	閲覧している環境（式の環境変数）	どこでも
row・rows[n]・size(rows)	<SqlView> の結果の行（行の参照）	<SqlView> の中
<For> の as・index の変数	繰り返している行と、何回目か	<For> の中

• パラメータは、最後に実行したときの値を参照します。入力欄で変えただけの値は、実行するまで反映されません
• 一度も実行していないパラメータはゼロ値になります（文字は ''、日付は '1970-01-01'、数値は 0、複数の値は [] など）。型は式のパラメータの型にあります

値の書式

列をそのまま差し込む（{{ row.ts }}）と、列の型に合わせた書式で表示されます。式を通した値（計算の結果、条件で選んだ値など）には、書式が適用されません。書式は formatNumber()・formatDate() で指定します（式の書式）。

式	表示（JST の場合）
{{ row.ts }}	2026/9/30 12:34:56
{{ row.ok ? row.ts : '' }}	2026-09-30T03:34:56Z
{{ formatDate(row.ts, "dayjs", "M/D HH:mm") }}	9/30 12:34

• 書式は閲覧者の言語設定に、タイムスタンプは閲覧者のタイムゾーンに従います
• 書式を適用した値は文字列です。条件では、書式を適用する前の値で比較します
• 配列（複数の値を持つパラメータなど）は、, で区切って表示されます

SQL の実行結果の表示

<SqlView> は、SQL ブロックの実行結果を、中に書いた要素で表示します。

<SqlView id="…" page="…" sql="…" hideFrame>
  <Columns>
    <Card title="売上">
      <Text size="2xl" weight="bold">{{ formatNumber(row.sales, "compact") }}</Text>
      <Text size="sm" color="muted">前月比 <Delta value="{{ row.mom }}" format=".1%" /></Text>
    </Card>
    <Card title="注文数">
      <Text size="2xl" weight="bold">{{ row.orders }}</Text>
    </Card>
  </Columns>
</SqlView>

• 中には、<Chart>・<Parameter>・<Tabs>・<Image> などは書けません。<SqlView> の外に書きます
• 中に <Card> を並べるときは、hideFrame を書いて枠の重なりを避けます
• <SqlView> はクロスフィルタに参加しません

行の参照

書き方	内容
row	1 行目（rows[0] と同じ）
rows[n]	n 行目（0 から数える）。n は整数のリテラルだけ
size(rows)	受け取った行の数

• 列は row.sales で参照します。名前が ASCII の識別子でない列は row['売上'] で参照します
• 受け取るのは、結果の先頭から 1,000 行までです。全体の件数や合計は、SQL で列として返します
• 0 行のときも中は表示されます。<If condition="{{ size(rows) == 0 }}"> でメッセージを表示します
• 実行結果にない列を参照すると、スキーマエラーになります。スキーマエラーは cdm notebook validate では検出されず、cdm notebook run ではステータスが ERROR になります
• <ParameterOverride> で上書きしても、中の param_<ID> はページのパラメータの値のままです

列の型

列の型	式での型
整数・小数	数値
文字列	文字列
真偽値	真偽値
日付	文字列（YYYY-MM-DD）
日時・タイムスタンプ	文字列（ISO 8601）
NULL	null
時刻・配列・構造体・JSON など	参照できない

条件と繰り返し

制御要素（<If>・<ElseIf>・<Else>・<For>）は、独自の枠を持ちません。子は、親の中に直接書いたものとして並べられます。たとえば <Columns> の中の <For> は、繰り返した 1 回分が 1 列になります。

出し分け

<If condition="{{ param_6a1000000000000000000012 == 'JP' }}">
  <Text>国内の売上</Text>
</If>
<Else>
  <Text>海外の売上</Text>
</Else>

• <ElseIf>・<Else> は、<If> か <ElseIf> の直後に書きます。最初に真になったものだけが表示されます
• 非表示の中身でも、クエリは実行され、閲覧者に送信されます。データを見せない目的には使えません
• 閲覧している環境で出し分けるときは env.<名前> を使います（env.mobile・env.print など）

繰り返し

<For> は、<SqlView> の結果の行ごとに子を繰り返します。<SqlView> の中にだけ書けます。入れ子にはできません。

<SqlView id="…" page="…" sql="…">
  <Columns>
    <For as="r" index="i" orderBy="{{ r.sales }}" desc limit="3">
      <Card title="{{ i }}位 {{ r.name }}">
        <Text size="xl" weight="bold">{{ r.sales }}</Text>
      </Card>
    </For>
  </Columns>
</SqlView>

• 行は as の名前で、何回目か（1 から）は index の名前で参照します
• where で行を選び、orderBy・desc で並べ替え、limit で回数を絞ります
• 直後に <Else> を書くと、1 回も繰り返さなかったときに表示されます
• 条件に合う行があるときだけ表示するには、<For where="{{ … }}" limit="1"> を使います

<List>・<Table> の中に制御要素を書くときは、その中に <ListItem>・<TableRow> を書きます。

表示の切り替え

閲覧者がページで変えられるものは、次の 3 つです。

• 表示の状態：見た目だけを変えます。SQL は実行しません
• パラメータ：SQL に渡され、データを変えます
• クロスフィルタ：チャートの選択を、ほかのチャートに連動させます

表示の状態

<Select>・<Switch>・<Tabs>・<Collapse> に as で名前を付けると、ページのどこからでも view.<名前> で状態を参照できます。状態は閲覧者ごとに独立しており、保存されません。

<Select as="metric" variant="segmented">
  <SelectOption value="sales" title="売上" default />
  <SelectOption value="orders" title="注文数" />
</Select>
<If condition="{{ view.metric == 'orders' }}">
  <Chart id="…" page="…" chart="…" />
</If>
<Else>
  <Chart id="…" page="…" chart="…" />
</Else>

要素	view.<名前> の値
<Select>	選んでいる <SelectOption> の value
<Switch>	オンか（真偽値）
<Tabs>	選んでいる <Tab> の value
<Collapse>	開いているか（真偽値）

• 同じ as を書いた要素は、状態を共有します（<Tabs> を切り替える <Select> など）
• PDF とスクリーンショットは、既定の状態で表示されます
• 切り替える中身が 1 か所なら、<Tabs> だけで十分です

パラメータと実行

既定では、パラメータの値を変えてもページは実行されません。<Parameter> に autoRun を書くと、値が確定したときに、そのパラメータを参照している要素が実行されます。

クロスフィルタ

<Chart> などの中に <CrossFilter> を書くと、グリッドページと同じく、凡例や軸の選択を連動させられます。

大きさと並べ方

• <Columns> は横、<Rows> は縦、<Grid> は格子に子を並べます。そのほかの要素の中では、子は縦に並びます
• 幅は親で決まります。<Columns> の子は grow の比で幅を分け、grow="0" の子は中身の幅になります
• 高さは height="320px" のように px で書きます。指定しない場合は、中身に合わせて決まります（<Chart>・<SqlResult> は 360px）
• <Columns> の子の高さは、既定では最も高い子にそろいます
• タブの切り替えや開閉で高さが変わります。高さを固定するときは height を書きます
• モバイル表示では、<Columns>・<Grid> の子は縦一列に並びます。表示を変えるときは env.mobile で出し分けます

エラーの種類

マークアップページのエラーには、構文エラー・スキーマエラー・実行時エラーの 3 種類があります。

種類	内容	cdm notebook validate	cdm notebook run
構文エラー	コードだけで分かる誤り	検出される	SQL を実行する前に失敗する
スキーマエラー	SQL の実行結果のスキーマ（列の名前と型）に合わないコード	検出されない	ステータスが ERROR になる
実行時エラー	SQL の実行結果やパラメータの値を当てはめて描画するときに、値を求められない式	検出されない	ステータスが WARNING になる

構文エラー

構文エラーは、コードだけで分かる誤りです。書き方の誤りのほか、値の型や参照先の誤りも含みます。

• 書き方の誤り：閉じていないタグ、存在しない要素や属性、指定されていない必須の属性、書けない場所にある要素、重複した ID、構文に誤りのある式など
• 値の型や参照先の誤り：属性に書けない値、型の合わない比較や計算、存在しないパラメータ・ページ・SQL ブロックへの参照など

選ばれなかった分岐や <For> の中も含めて、ページのすべてのコードが検査されます。構文エラーが 1 つでもあると、cdm notebook push・cdm notebook run などは失敗します。

スキーマエラー

スキーマエラーは、SQL の実行結果の列の名前や型によって決まる誤りです。実行結果にない列の参照のほか、列の型に合わない比較や計算、配列など参照できない型の列の参照も含みます。

• 構文エラーと同じく、ページのすべてのコードが検査されます
• スキーマは SQL を実行するまで確定しないため、cdm notebook validate では検出されません。cdm notebook run では、ステータスが ERROR になります

実行時エラー

実行時エラーは、SQL の実行結果やパラメータの値を当てはめて描画するときに、値を求められない式があると発生します。たとえば、次のような式が該当します。

• null との大小比較（row.x > 0 で、x が NULL の場合）
• 0 による除算
• SQL の実行結果が 0 行のときの row の参照（row は 1 行目を表すため）

実行時エラーが発生するかどうかは、データによって異なります。そのため、cdm notebook run では、<SqlView> の中の式の実行時エラーは、ERROR ではなく WARNING になります。

• 計算されるのは、描画される部分の式だけです。選ばれなかった <If>・<ElseIf>・<Else> の中や、1 回も繰り返さない <For> の中の式は計算されません
  • cdm notebook run で WARNING にならなくても、データの変化によって別の部分が描画されると、その部分の式は実行時エラーになる場合があります
• 実行時エラーになった式の値は、条件では偽、差し込みでは空、色などの属性では既定値として扱われます
• NULL になりうる列を比較するときは、先に null かどうかを判定します（row.x != null && row.x > 0）