Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

カスタムビジュアリゼーション API 2.0 リファレンス

looker.plugins.visualizations.add 関数への呼び出しは、Visualization API のエントリポイントです。この関数は、カスタムビジュアリゼーションを完全に定義するビジュアリゼーションオブジェクトを受け入れます。

ビジュアリゼーションの例を次に示します。

looker.plugins.visualizations.add({
    create: function(element, config){
        element.innerHTML = "<h1>Ready to render!</h1>";
    },
    updateAsync: function(data, element, config, queryResponse, details, doneRendering){
        var html = "";
        for(var row of data) {
            var cell = row[queryResponse.fields.dimensions[0].name];
            html += LookerCharts.Utils.htmlForCell(cell);
        }
        element.innerHTML = html;
        doneRendering()
    }
});

環境

Visualization API はプレーンな JavaScript であるため、任意の JavaScript ライブラリを使用してデータを可視化できます。

JavaScript コードは、Looker インスタンスとは別のサンドボックス化された iframe で実行されます。カスタムビジュアリゼーションの作成者は、記述するコードが安全であることを確認する必要があります。

すべてのウェブ開発と同様に、さまざまなウェブブラウザ（Chrome、Edge、Firefox）のサポートが問題になることがあります。Visualization API は、Looker がサポートするすべてのブラウザで動作しますが、カスタムコードのブラウザサポートを確保するのはユーザーの責任です。たとえば、let や ()=> などの ES6 の使用はほとんどのブラウザで機能しますが、IE11 でエラーが発生したり、PhantomJS を使用して PDF をレンダリングしたりする可能性があります。

インストール

カスタムビジュアリゼーションをインストールするには、[Admin] > [Platform] > [Visualizations] フォームでマニフェストを定義します。マニフェストは、一意の文字列 ID、人が読める形式のラベル、ビジュアリゼーションの URI、必要な依存関係（d3、jQuery、underscore など）へのリンクで構成されます。

カスタムビジュアリゼーションは、Looker の外部で HTTPS コンテンツとして提供する必要があります。カスタムビジュアリゼーション API の最初のバージョンから移行する場合は、looker/plugins/visualizations ディレクトリにファイルがある可能性があります。この場所には引き続きアクセスでき、ビジュアリゼーションへの相対パスを指定できますが、コンテンツを別の場所に移行することをおすすめします。/plugins ディレクトリは共有ファイルシステムにないため、クラスタ化された環境では、すべてのノードでビジュアリゼーションファイルにアクセスできません。

ビジュアリゼーションオブジェクト

ビジュアリゼーションオブジェクトは、次の必須プロパティ、オプションプロパティ、追加プロパティを使用します。

必須プロパティ

create 関数

この関数は、ビジュアリゼーションがページに初めて描画されるときに 1 回呼び出されます。ビジュアリゼーションで常に使用できるようにするものを設定することが想定されています。ライブラリを読み込んだり、後で使用する要素とコントロールのセットを作成したりできます。

create 関数の詳細を見る →
updateAsync / update 関数

この関数は、ビジュアリゼーションの状態を変更する必要があるたびに呼び出されます。常に create の後に呼び出され、何度も呼び出される可能性があるため、できるだけ高速にする必要があります。

この関数はさまざまな理由で呼び出すことができますが、通常は、可視化するクエリが変更された場合、構成オプションが変更された場合、またはビジュアリゼーションのサイズが変更された場合です。

この関数には同期バージョンと非同期バージョンがあります。1 つだけ指定する必要があります。（両方を定義するとエラーになります）。iframe の特性上、PDF レンダリングでは非同期メソッドの方が信頼性が高くなります。

これらの update 関数の詳細を見る →

オプションのプロパティ

options オブジェクト

ユーザーがビジュアリゼーションで設定できるオプションの詳細を示すオブジェクト。

構成 UI の公開の詳細を見る →
destroy function __API V2 ではまだ実装されていません

ビジュアリゼーションがページから削除される直前に呼び出される関数。この関数を使用して、イベントリスナーやその他の状態をクリーンアップします。たとえば、ユーザーがウィンドウを閉じると、呼び出されないことがあります。

広告プロパティ

ビジュアリゼーションが looker.plugins.visualizations.add に渡されると、Looker は次のプロパティをオブジェクトに自動的に追加します。create、update、updateAsync、destroy 関数のコンテキスト内で this を使用して参照できます。

addError 関数

ビジュアリゼーションコードが呼び出して、ビジュアリゼーションの代わりにエラーメッセージを表示するように UI に指示する関数。error オブジェクトを受け取ります。

エラーが追加されると、clearErrors が呼び出されるまで表示されたままになります。

例:
```
this.addError({
    title: "Two Dimensions Required",
    message: "This really great visualization requires two dimensions."
});
```
clearErrors 関数

ビジュアリゼーションコードが呼び出して、addError を使用して追加されたエラーをクリアする関数。

例:
```
this.clearErrors();
```
trigger 関数

ビジュアリゼーションの外部でイベントをトリガーするために呼び出すことができる関数。

イベントの詳細を見る →

例:
```
this.trigger("limit", [20]);
```

`create` 関数

create 関数には、element と config の 2 つのパラメータが渡されます。

create: function(element, config){
  // Your update code here.
},

パラメータ

element DOMElement DOMElement

ビジュアリゼーションをレンダリングするコンテナを表す DOM 要素。
config オブジェクト

ユーザーがこのグラフに設定した構成オプションの値を表すオブジェクト。

例: {my_configuration_option: "User Value"}

`updateAsync` 関数と `update` 関数

ビジュアリゼーションを更新する推奨の方法は、updateAsync メソッドです。このメソッドを使用すると、ビジュアリゼーションでファイルの読み込みやウェブリクエストの送信などの非同期アクションを実行できます。

このバージョンの関数には、レンダリングが完了したときに呼び出されるコールバックという追加のパラメータがあります。

updateAsync: function(data, element, config, queryResponse, details, done){
    // An example of an asynchronous update, fetching a file.
    d3.request("https://example.com/fun-file.docx").response(function(xhr) {
        // Your update code here that uses this file.
        done();
    });
}

ビジュアリゼーションのレンダリングが完了したときに Looker に通知することで、Looker は PDF レンダリングを最適化し、ビジュアリゼーションの画像が適切にキャプチャされるようにします。

古いビジュアリゼーションでは update 関数が使用されています。この関数は引き続き機能しますが、ビジュアリゼーションが完全にレンダリングされたときに Looker に通知されないため、推奨される方法ではありません。update 関数には 5 つのパラメータが渡されます。

update: function(data, element, config, queryResponse, details){
  // Your update code here.
}

パラメータ

data 配列

クエリ内の現在のデータを表す行の配列。null も可能です。

各行は、フィールド名を表すキーと「セル」オブジェクトを表す値を持つオブジェクトです。セルオブジェクトの処理の詳細については、こちらをご覧ください。
element DOMElement DOMElement

ビジュアリゼーションをレンダリングするコンテナを表す DOM 要素。
config オブジェクト

ユーザーがこのグラフに設定した構成オプションの値を表すオブジェクト。

例: {my_configuration_option: "User Value"}
queryResponse オブジェクト

フィールドに関するメタデータなど、現在のクエリに関するメタデータを表すオブジェクト。null も可能です。
details オブジェクト

現在のレンダリングコンテキストの詳細。グラフがレンダリングされる理由と変更内容に関する情報が含まれています。通常、この情報は高度なケースでのみ使用されます。

新しいダッシュボードエクスペリエンスを使用する Looker ダッシュボードのクロスフィルタについては、使用できる属性はcrossfilterEnabledとcrossfiltersです。

print 属性を done 関数と組み合わせて使用すると、カスタムビジュアリゼーション（特にアニメーションを含むビジュアリゼーション）の PDF レンダリングを改善できます。次に例を示します。
```
if (details.print) {
        done();
}
```
done 関数

ビジュアリゼーションが完全にレンダリングされたことを示すコールバック。この呼び出しは、ビジュアリゼーションが非同期呼び出しを実行する必要がある場合、または PDF としてレンダリングする必要がある場合は、特に重要です。

データのレンダリング

Looker には、LookML でデータポイントの外観と動作をカスタマイズするために使用できる豊富なデータ形式設定ツールが用意されています。これらのツールには、カスタム値形式、HTML、ドリルリンク、データアクションなどのフィールドレベルの LookML 設定が含まれます。

セルには value プロパティがあります。これは、すべての場合に存在する唯一のプロパティです。このプロパティは、セルが属するフィールドの型と一致する JavaScript 型です。ただし、HTML エスケープが実行されていないため、value プロパティを HTML または SVG に直接挿入することは安全ではありません。また、一部のフィールド値は複雑な JavaScript オブジェクトまたは配列であり、望ましくない方法やわかりにくい方法でレンダリングされます。

すべてのビジュアリゼーションでこれらのアイテムが一貫して安全にレンダリングされるように、data でグラフに渡されるセルメタデータをさまざまな目的に合わせてさまざまな表現に変換するためのユーティリティ関数が用意されています。セルメタデータは、場合によっては特定のフィールドを圧縮または省略することがありますが、これらのヘルパー関数を使用すると、一貫したエクスペリエンスを提供できます。

これらのヘルパー関数はすべて、グローバル LookerCharts.Utils オブジェクトで使用できます。

LookerCharts.Utils.textForCell(cell)

この関数はセルを受け取り、表示に適した文字列表現を返します。常に文字列になります。この関数は null やその他の型を返しません。
LookerCharts.Utils.htmlForCell(cell)

この関数はセルを受け取り、HTML を含む文字列を返します。常に文字列になります。この関数は null やその他の型を返しません。

この関数の出力は適切にエスケープされ、要素の HTML に直接挿入するのに適しています。出力 HTML では、データに適している場合は、クリック時にドリルメニューも正しく表示されます。
LookerCharts.Utils.filterableValueForCell(cell)

この関数はセルを受け取り、このセルの値に一致する Looker の高度なフィルタ構文文字列を返します。
LookerCharts.Utils.toggleCrossfilter({row, pivot, event})

この関数は、行、ピボット、またはイベントを受け取り、ビジュアリゼーションでクロスフィルタが有効になっているかどうかを確認するために使用されます。次の例は、イベントが発生したときにクロスフィルタが有効になっているかどうかを確認するイベントリスナーを要素に追加する方法を示しています。
```
d3.select("#myElement")
.on("click", function (d) {
    if (details.crossfilterEnabled) {
            LookerCharts.Utils.toggleCrossfilter({
                row: d.row,
                event: d3.event,
            });
    } else {
      // ... handle click when cross-filtering is not enabled
    }
});
```
LookerCharts.Utils.getCrossfilterSelection(row, pivot?)

この関数は、行またはピボットを受け取り、その行またはピボットがカスタムビジュアリゼーションで選択されているかどうかを確認するために使用されます。この関数は、CrossfilterSelection {NONE, SELECTED, UNSELECTED} の列挙型を返します。NONE の場合は 0、SELECTED の場合は 1、UNSELECTED の場合は 2 です。

次の例では、行がクロスフィルタされている場合は、条件付きで塗りつぶしの色を適用し、その行でクロスフィルタが有効になっていない場合は、デフォルトの色を適用します。
```
d3.select("#myElement")
.attr("fill", function (d) {
    const crossfilter = LookerCharts.Utils.getCrossfilterSelection(d.row)
    if (details.crossfilterEnabled && crossfilter === 1) {
            return d.color
    } else {
            return "#DEE1E5" //Hex used for unselected elements in native visualizations
...
```
LookerCharts.Utils.openDrillMenu(options)

htmlForCell の出力では、必要に応じてドリルメニューが自動的に表示されますが、特定の種類のレンダリングには適していない場合があります。（たとえば、SVG は HTML をレンダリングできませんが、クリックイベントをキャプチャしてドリルを開始できます）。

options オブジェクトには次のパラメータがあります。
- links 必須配列
  
  セルの links プロパティから返されたオブジェクトの配列。複数のセルのリンクを一度に表示する場合は、まずこれらの配列を連結します。カスタムリンクの場合は、次の形式のオブジェクトの配列を指定します。
```
{ label: string, type: 'drill', type_label: string, url: url }
```
- event HTML DOM イベント
  
  ドリルイベントの原因となったクリック（またはその他の）イベント。Looker はこれを使用して、ドリルメニューの配置場所を決定します。ない場合は、pageX 座標と pageY 座標を持つオブジェクトを渡してみてください。
例:
```
for (var row of data) {
    var cell = row[queryResponse.fields.dimensions[0].name];
    var cellElement = myBuildElementFunction(cell);
    cellElement.onclick = function(event) {
        LookerCharts.Utils.openDrillMenu({
            links: cell.links,
            event: event
        });
    };
    // ... more visualization stuff...
}
```

構成 UI の表示

options パラメータは、キーがオプション名の任意の識別子で、値がオプションに関する情報を記述するオブジェクトであるオブジェクトです。

次に例を示します。

options: {
    color_range: {
      type: "array",
      label: "Color Range",
      display: "colors"
    },
   top_label: {
      type: "string",
      label: "Label (for top)",
      placeholder: "My Great Chart"
    },
    transport_mode: {
      type: "string",
      label: "Mode of Transport",
      display: "select",
      values: [
         {"Airplane": "airplane"},
         {"Car": "car"},
         {"Unicycle": "unicycle"}
      ],
      default: "unicycle"
    }
}

オプションオブジェクトパラメータ

option オブジェクトには、次の基本パラメータ、表示固有のプロパティ、整理オプションがあります。

基本パラメータ

type 文字列

オプションのデータ型。

使用できる値: string（デフォルト）、number、boolean、array
label 文字列

ユーザーに表示されるオプションの人が読める形式のラベル。
default

オプションのデフォルト値。指定しない場合、オプションの値は null になります。type と同じ型の値にする必要があります。
display 文字列

特定の type 値は、UI でさまざまな方法で表示できます。
- type が string の場合:
  
  使用できる値: text（デフォルト）、select、radio
- type が number の場合:
  
  使用できる値: number（デフォルト）、range
- type が array の場合:
  
  使用できる値: text（デフォルト）、color、colors
placeholder 文字列

サポートされている display 値の場合、ユーザーが入力する内容のヒントとなる値または説明の例。

表示固有のプロパティ

values オブジェクトの配列

display が radio または select の場合、インターフェースに表示されるラベルと値を含む配列。

配列内の各アイテムは、オプションのラベルと値を表す単一の Key-Value ペアを持つオブジェクトにする必要があります。ラベルは UI でのみ表示されます。レンダリング時には値のみが返されます。

例:
```
values: [
    {"Center": "c"},
    {"Left": "l"},
    {"Right": "r"}
]
```
display が radio の場合、各オプションに description を追加できます。
```
values: [
    {"Cool": "c"},
    {"Uncool": {
            value: "unc",
            description: "Only choose this if the data is very uncool."
        }
    }
]
```
max number

display が range の場合、範囲スライダーで選択できる最大数。
min number

display が range の場合、範囲スライダーで選択できる最小数。
step number

display が range の場合、範囲スライダーの各目盛りが表す量。

オプションの整理

section 文字列

オプションが多いグラフの場合、オプションを表示するセクションのラベル。UI では、オプションが section 値でグループ化されます。セクションが 1 つしかない場合、セクション UI は表示されません。

section を使用する場合は、すべてのオプションに設定する必要があります。
order number

UI での表示順序を表す数値。指定すると、オプションはこの順序で並べ替えられます。
display_size 文字列

UI でのオプションの幅を表すサイズクラス。たとえば、「最小」オプションと「最大」オプションを並べて表示する場合は、それぞれの表示サイズを half に設定します。

使用できる値: normal（デフォルト）、half、third

イベント

イベントは、グラフによってトリガーされ（通常はユーザー操作に応じて）、ビジュアリゼーションまたはクエリのプロパティを更新できます。

ビジュアリゼーションオブジェクトで trigger 関数を呼び出すことでトリガーできます。最初のパラメータは常にイベント名で、2 番目のパラメータは引数の配列です。

this.trigger("limit", [20]);

使用可能なイベント

updateConfig

グラフの現在の構成設定を更新します。

引数: 更新する構成キーを含むオブジェクト。指定されていないキーは変更されません。

例:
```
var vis = this;
$(element).find(".axis").click(function(){
    vis.trigger("updateConfig", [{axis_hidden: true}]);
});
```

limit

基盤となるクエリの上限を更新します。

引数: クエリの新しい上限を表す整数。

var vis = this;
$(element).find(".show-all").click(function(){
    vis.trigger("limit", [500]);
});

filter

基盤となるクエリのフィルタの値を更新します。

var vis = this;
$(element).find(".show-all-tommys").click(function(){
    vis.trigger("filter", [{
        field: "users.name", // the name of the field to filter
        value: "%tommy%", // the "advanced syntax" for the filter
        run: true, // whether to re-run the query with the new filter
    }]);
});

loadingStart

ビジュアリゼーションを読み込み中としてマークします。ほとんどの場合、これは必要ありませんが、ビジュアリゼーションがリモートの場所からオブジェクトを読み込む場合や、長い計算を実行する場合は、これを使用して読み込みインジケーターを引き続き表示できます。

loadingEnd がトリガーされるまで読み込み中と表示されます。
loadingEnd

ビジュアリゼーションを読み込み中ではなくします。
printSize（Looker 26.0 以降）

ダッシュボードを PDF にレンダリングする際に、ビジュアリゼーションで [テーブルを展開してすべての行を表示] オプションを利用できるようにします。このイベントを使用すると、レンダリングされたコンテンツの高さをアプリケーションで把握し、すべての情報が印刷できるようにダッシュボードタイルを適切に展開できます。
```
  this.trigger('printSize', {
    heightExpanded: FULL_HEIGHT_IN_PIXELS
  });
```

registerOptions（Looker 5.24 以降）

ビジュアリゼーションが登録された後、ビジュアリゼーションで追加のオプションを登録できるようにします。

  update: function(data, element, config, queryResponse, details){
    options = {}
    // Create an option for each measure in your query
    queryResponse.fields.measure_like.forEach(function(field) {
      id = "color_" + field.name
      options[id] =
      {
    label: field.label_short + " Color",
    default: "#8B7DA8",
    section: "Style",
    type: "string",
    display: "color"
      }
    })
    this.trigger('registerOptions', options) // register options with parent page to update visConfig
    ...
  }
});

カスタム ビジュアリゼーション API 2.0 リファレンス コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

環境

インストール

ビジュアリゼーション オブジェクト

必須プロパティ

オプションのプロパティ

広告プロパティ

create 関数

パラメータ

updateAsync 関数と update 関数

パラメータ

データのレンダリング

構成 UI の表示

オプション オブジェクト パラメータ

基本パラメータ

表示固有のプロパティ

オプションの整理

イベント

使用可能なイベント

カスタムビジュアリゼーション API 2.0 リファレンス

ビジュアリゼーションオブジェクト

`create` 関数

`updateAsync` 関数と `update` 関数

オプションオブジェクトパラメータ