Codatum CLI

Appearance

グリッドページ ​

概要 ​

  • ノートブックファイル内のグリッドページでは、ドキュメントページで定義したSQLブロックの実行結果やチャートを、ダッシュボードとしてレイアウトできます
  • グリッドページは以下の構造により記述します
    • yaml {.page} によるページ属性
    • :::grid-item によるグリッド内に配置する要素の定義
    • yaml {.grid-layout} によるグリッドのレイアウト定義

ページ属性 ​

  • ページ属性は yaml {.page} のコードブロックとして次のオブジェクト型で表現します
    • id はノートブックファイル内でユニークな値を指定します
      • 未指定の場合、 format 実行時に自動付与されます
    • width にはページ幅を指定します
      • デフォルトは { width_type: 'AUTO' } で、画面幅に合わせて伸縮します
    • パラメータに関する説明は パラメータ を参照してください
ts
type GridPageAttrs = {
  type: 'GRID_PAGE';
  id: ObjectId;
  width?:
    | { width_type: 'AUTO' }
    | { width_type: 'FIXED'; fixed_width: 640 | 800 | 1024 | 1280 | 1366 | 1600 }
    | {
        width_type: 'RANGE';
        min_width?: 640 | 800 | 1024 | 1280 | 1366 | 1600;
        max_width?: 640 | 800 | 1024 | 1280 | 1366 | 1600;
      };

  // パラメータの説明を参照
  notebook_param_widget_values?: ParamWidgetValue[];
  page_param_widgets?: ParamWidget[];
  page_param_widget_values?: ParamWidgetValue[];
};

グリッド要素 ​

  • グリッドに配置する要素をコンテナディレクティブ :::grid-item により記述します
    • :::grid-item はグリッド内に配置する要素の数だけ記述します
    • 要素の属性を yaml {.attrs} のコードブロックとして記述します
      • id にはページ内でユニークな値を指定します（未指定の場合は自動生成されます）
        • 互換性のため、 ObjectId の他に Uuid も指定可能ですが、 ObjectId の使用を推奨します
      • type により、要素の種類を指定し、残りの属性は type により異なります
      • description を指定すると、グリッド内に ? アイコンが表示され、マウスオーバーで指定した説明が表示されます
    • 要素の本文を属性に続けてマークダウンで記述します
      • type によって要素の本文が必要な場合と不要な場合があります

見出し ​

  • 見出しは次の属性定義を持ちます
  • 要素の本文には h2, h3, h4 のいずれかの見出しを指定します
ts
type HeadingAttrs = {
  type: "HEADING";
  id: ObjectId | Uuid;
  description?: string;
};

例 ​

md
:::grid-item
```yaml {.attrs}
type: HEADING
id: 69dac8455174dcb50b75eec1
description: Tooltip text here
```

## Example heading
:::

チャート ​

  • チャートは次の属性定義を持ち、ドキュメントページで定義したチャートを参照します
    • pageId でドキュメントページの id を、chartId で対象のチャートの id を指定します
    • overwriteParams を指定することで、パラメータの値を上書きできます
    • crossFilter については、クロスフィルタを参照してください
  • 要素の本文は不要です
  • jobId にはチャートのデータソースとして指定されたSQLブロックのジョブの、chartJobId にはチャート用のデータ加工に利用されたジョブのジョブリソースIDが付与されます
ts
type ChartAttrs = {
  type: "CHART";
  id: ObjectId | Uuid;
  pageId: ObjectId;
  chartId: ObjectId;
  name?: string;  // チャート名を指定
  description?: string;
  crossFilter?: CrossFilter;
  overwriteParams?: OverwriteParam;
  hideFrame?: boolean;  // グリッドの枠線を非表示にするか否か
  hideName?: boolean;  // チャート名を非表示にするか否か

  // 以下はクエリを実行した際に自動的に付与される
  jobId?: JobResourceId;
  state?: "DISPATCHED" | "ERROR" | "REMOVED";
  errorMessage?: string;
  chartJobId?: JobResourceId;
  chartJobQueryHash?: string;
};

例 ​

md
:::grid-item
```yaml {.attrs}
type: CHART
id: 69dac8455174dcb50b75eec3
pageId: 69dac8455174dcb50b75eec1
chartId: 69dac8455174dcb50b75eec2
```
:::

SQLブロックの実行結果 ​

  • SQLブロックの実行結果は次の属性定義を持ち、ドキュメントページで定義したSQLブロックの実行結果を参照します
    • pageId でドキュメントページの id を、sqlId で対象のSQLブロックの id を指定します
    • overwriteParams を指定することで、パラメータの値を上書きできます
    • crossFilter については、クロスフィルタを参照してください
  • 要素の本文は不要です
  • jobId には sqlId で指定されたSQLブロックのジョブのジョブリソースIDが付与されます
ts
type SqlBlockResultAttrs = {
  type: "SQL_BLOCK_RESULT";
  id: ObjectId | Uuid;
  pageId: ObjectId;
  sqlId: ObjectId;
  name?: string;  // テーブル名を指定
  description?: string;
  crossFilter?: CrossFilter;
  overwriteParams?: OverwriteParam[];
  hideFrame?: boolean;  // グリッドの枠線を非表示にするか否か
  hideName?: boolean;  // テーブル名を非表示にするか否か

  // 以下はクエリを実行した際に自動的に付与される
  jobId?: JobResourceId;
  state?: "DISPATCHED" | "ERROR" | "REMOVED";
  errorMessage?: string;
};

例 ​

md
:::grid-item
```yaml {.attrs}
type: SQL_BLOCK_RESULT
id: 69dac8455174dcb50b75eec4
pageId: 69dac8455174dcb50b75eec1
sqlId: 69dac8455174dcb50b75eec2
```
:::

リッチテキスト ​

  • リッチテキストは次の属性定義を持ちます
  • 要素の本文には以下のマークダウン要素のみ指定できます（ドキュメントページの本文とは利用可能な要素が異なります）
    • パラグラフ
    • リスト（箇条書き）(-, 1.)
    • 引用(>)
ts
type RichTextAttrs = {
  type: "RICH_TEXT";
  id: ObjectId | Uuid;
  name?: string;  // ブロック名を指定
  hideFrame?: boolean;  // グリッドの枠線を非表示にするか否か
  hideName?: boolean;  // ブロック名を非表示にするか否か
};

例 ​

md
:::grid-item
```yaml {.attrs}
type: RICH_TEXT
id: 69dac8455174dcb50b75eec5
name: 補足事項
```

- 売上には発送後のキャンセル分は未反映
- 配送料は含まない
:::

スペーサー ​

  • スペーサーはレイアウトの調整を行うための空要素で、次の属性定義を持ちます
  • 要素の本文は不要です
ts
type SpacerAttrs = {
  type: "SPACER";
  id: ObjectId | Uuid;
  showOnMobileLayout?: boolean;
};

例 ​

md
:::grid-item
```yaml {.attrs}
type: SPACER
id: 69dac8455174dcb50b75eec6
```
:::

グリッドレイアウト ​

  • グリッドレイアウトは次の GridLayout 型で表現される配列を yaml {.grid-layout} のコードブロックとして記述します
    • ref はグリッド要素の id を指定します
    • height はグリッド要素の高さを整数(n >= 1)で指定します
      • 実際の高さは {n * 60 - 20}px になります
      • 要素ごとの初期値は次の通りです
        • 見出し、スペーサー: 1
        • リッチテキスト: 3
        • チャート等のその他要素: 6
    • width はグリッド要素の幅を 1-12 の範囲の整数で指定します
      • children の合計の width が 12 になるように指定する必要があります
    • rows は columns の子としてのみ使用できます（ルート直下には置けません）
  • :::grid-item により定義されたグリッド要素で、レイアウトから未参照のものは format を実行するとレイアウトの末尾に自動追加されます
ts
type LeafNode = {
  type: 'leaf';
  ref: ObjectId | Uuid;
  height?: number;  // 未指定時は 6
};

type RowsNode = {
  type: 'rows';
  children: (LeafNode | ColumnsNode)[];
};

type ColumnsNode = {
  type: 'columns';
  children: ((LeafNode | RowsNode) & { width: number })[];
};

type GridLayout = (LeafNode | ColumnsNode)[];

例 ​

yaml
- type: columns
  children:
    - type: leaf
      ref: 69dac8455174dcb50b75eec1
      height: 2
      width: 8
    - type: leaf
      ref: 69dac8455174dcb50b75eec2
      height: 2
      width: 4
- type: columns
  children:
    - type: leaf
      ref: 69dac8455174dcb50b75eec3
      height: 4
      width: 4
    - type: leaf
      ref: 69dac8455174dcb50b75eec4
      height: 4
      width: 4
    - type: leaf
      ref: 69dac8455174dcb50b75eec5
      height: 4
      width: 4
- type: columns
  children:
    - type: rows
      width: 4
      children:
        - type: leaf
          ref: 69dac8455174dcb50b75eec6
          height: 5
        - type: leaf
          ref: 69dac8455174dcb50b75eec7
          height: 5
    - type: leaf
      ref: 69dac8455174dcb50b75eec8
      height: 10
      width: 8
- type: leaf
  ref: 69dac8455174dcb50b75eec9
  height: 8