コンテンツにスキップ

ルーティング: データバインディング

データバインディングは、CMSoD のデータストアに格納されているコンテンツ（ニュース記事・商品データ・コレクションのエントリなど）を取得し、HTML テンプレートに差し込む仕組みです。これにより、HTML を 1 つ用意するだけで複数の動的ページを生成できます。

このページは ルート設定 の続きです。先にルートの基本概念を確認しておいてください。

バインドの基本設定

1 つのルートに対して、1 つ以上の「バインド」を設定できます。それぞれのバインドが「どのデータを、どのような条件で取得するか」を定義します。

項目 説明 必須
バインド名 このバインドの識別名（最大 64 文字、英数字） はい
バインドドメイン データ取得元のコレクション はい
クエリ 取得条件（JSON 形式） はい
ソート 取得結果の並び順 いいえ
件数制限 最大取得件数 いいえ
1 件のみ取得 チェックすると 1 件のみ取得 いいえ
結果なし時に 404 取得結果が 0 件のときに 404 を返す いいえ

ルート編集ダイアログのバインド設定セクション

「バインド名」はテンプレートからデータを参照するときの名前として使われます。後から変更すると、参照箇所もまとめて修正する必要があるため、最初に決めた名前を維持することを推奨します。

クエリの記述

クエリは、データ取得条件を JSON 形式で記述します。比較演算子（$eq $gt 等）と論理演算子（$and $or）を組み合わせた JSON ベースのクエリ DSL です。

単純な条件

{
  "status": "published"
}

→ status フィールドが published のレコードのみ取得。

URL パラメータの参照

URL パターンに :id のようなパラメータがある場合、クエリ内から参照できます。

{
  "_id": ":id"
}

→ パスパラメータ :id の値が _id に一致するレコードを取得。

よく使う比較演算子

演算子 意味 例
$eq 等しい {"status": {"$eq": "active"}}
$ne 等しくない {"status": {"$ne": "draft"}}
$gt より大きい {"count": {"$gt": 10}}
$gte 以上 {"count": {"$gte": 10}}
$lt より小さい {"count": {"$lt": 100}}
$lte 以下 {"count": {"$lte": 100}}
$in いずれかに一致 {"category": {"$in": ["news", "blog"]}}
$nin いずれにも一致しない {"category": {"$nin": ["draft"]}}
$exists フィールドの有無 {"thumbnail": {"$exists": true}}
$and AND 条件 {"$and": [{...}, {...}]}
$or OR 条件 {"$or": [{...}, {...}]}

よくあるエラー

エラー 原因 対処
クエリ構文エラー JSON として不正、引用符の閉じ忘れ エディタの構文チェックを確認
フィールド名のタイポ 存在しないフィールドを指定 コレクションのフィールド一覧で確認
結果が常に 0 件 値の型不一致（数値を文字列で比較等） データを開いて型を確認

バインドのパラメータルール

バインドごとに、受け付ける URL クエリパラメータのルールを定義できます。

項目 説明
キー パラメータ名（英数字）
必須 true / false
デフォルト値 パラメータ未指定時の既定値

たとえば検索結果ページで ?keyword=... を受け取り、未指定時は空文字をデフォルトにするといった用途で使います。

ページネーション

取得結果をページ単位で区切って表示できます。

項目 説明
有効/無効 ページネーションのオン／オフ
1 ページあたりの件数 表示件数
プレフィックス URL パラメータのプレフィックス（最大 64 文字）

プレフィックスを設定しておくと、複数のバインドを 1 ページに置いてもそれぞれ独立したページネーションが可能になります（例: news_page=2&blog_page=3）。

グルーピング

取得結果を特定のフィールドでグループ化できます。

項目 説明
有効/無効 グルーピングのオン／オフ
グループキー グループ化するフィールド名

「年月別のアーカイブ一覧」や「カテゴリ別の商品リスト」など、見出し付きの一覧表示で利用します。

カスタムフォーマット

バインドで取得したデータを、テンプレートに渡す前に加工する仕組みです。フィールド値の変換、参照解決（外部キー → 実データ）、フィルタリングなどに使います。

設定項目

項目 説明 必須
キー フォーマット対象のフィールド名（最大 64 文字、英数字・アンダースコア・ハイフン） はい
値 フォーマット定義（JSON 形式） はい
バインド名 適用対象のバインド名。省略時は全バインド いいえ

全バインドに適用 / 特定バインドに適用

カスタムフォーマットは内部的にバインド名でグループ化されます。

{
  "*": {                    ← 全バインドに適用
    "key1": value1
  },
  "bind-name": {            ← 特定バインドにのみ適用
    "key1": value2
  }
}

バインド名を省略すると *（全バインド対象）として扱われます。

値の記述形式

JSON で次の 3 形式が記述できます。

形式 説明
単純な値 固定値への変換
マップ（オブジェクト） クエリ形式でフィルタリング
配列形式 参照先データの取得とソート指定

参照＋ソート指定の構文:

[[参照フィールド1, 参照フィールド2], {フィルタ条件}, [ソートフィールド, "asc"]]
  • ソート順は asc（昇順）または desc（降順）

セレクター構文

カスタムフォーマットの値では、ネストされたデータに簡潔にアクセスするためのセレクター構文を使えます。

:parent [:id="5"] :nth(1)
構文 説明
:field-name フィールドへのアクセス
[:attr="value"] 属性でフィルタリング
:nth(n) n 番目の要素
:length 要素数
:empty 空要素のみ
:not-empty 空でない要素のみ
:has(...) 条件に一致する要素

属性フィルターの演算子:

演算子 意味
= 等しい
!= 等しくない
~= 部分一致
^= 前方一致
$= 後方一致
<、<=、>、>= 数値の比較

よく使うパターン例

1. ステータスでの絞り込み

公開済みエントリのみを返す:

{
  "*": {
    "status": "published"
  }
}

2. 参照解決（外部キー → 実データ）

author_id が指している実際の author レコードを引き当てて差し込みます。

{
  "articles": {
    "author": [["author_id"], {}, ["display_name", "asc"]]
  }
}

→ articles.author_id を主キーに author コレクションを引き、表示用に display_name 昇順で並べ替えて articles.author に詰めます。

3. 配列要素の取り出し（セレクター）

tags の 1 番目のタグだけを取り出す:

{
  "articles": {
    "primary_tag": ":tags:nth(1)"
  }
}

4. 条件付きの絞り込み

comments のうち承認済みのみを取得:

{
  "articles": {
    "approved_comments": ":comments[:status=\"approved\"]"
  }
}

5. 全バインド共通の整形

すべてのバインドで日時フィールドを正規化したい場合は * キーを使います。

{
  "*": {
    "published_at": ":published_at"
  }
}

カスタムフォーマット適用後の値は、HTML テンプレート側で {{articles.author.display_name}} のように参照します。

パラメータルール

URL のクエリパラメータ全体に対する検証ルールです。バインド固有のルール（前述）と別に、ルート全体で受け付ける形式を定義します。

項目 説明
パラメータ名 対象のパラメータ名（最大 64 文字）
ルール 検証条件（正規表現）

条件テンプレート

同じルートでも、データの内容や URL パラメータに応じて異なるテンプレートを出し分けたい場合に使います。

タイプ 説明
クエリベース コレクションのクエリ結果でテンプレートを切替
バインドベース バインドのフィールド値でテンプレートを切替
パラメータベース URL パラメータの値でテンプレートを切替

条件に一致しない場合の既定テンプレートも指定できます。

次に読むページ