[Tableau] JavaScript API パラメータの設定

車輪開発大好きおたいがです。こんにちは。（挨拶）

今回は Tableau JavaScript API を介して表示したワークブックから取得できる「パラメータ」について紹介します。

Tableau の「パラメータ」は、ビューの表示内容を切り替える要素として提供されている機能のひとつです。詳細は下記記事をご覧ください。

『パラメータ』について｜Tableau Software Tips&Viz Advent Calendar 2014 #11 #tableau
https://dev.classmethod.jp/business/business-analytics/advent-calendar2014-tableau-parameter/

パラメータ情報の取得

パラメータ情報はワークブックから取得することができます。workbook.getParametersAsync() メソッドを使用することで、Promise オブジェクトを介して Parameter インスタンスの配列が取得可能です。

var options = {
  'hideTabs'           : false,
  'hideToolbar'        : false,
  'onFirstInteractive' : function () {
    workbook = viz.getWorkbook();
    var onSuccess = function(parameters) {
      $.each(parameters, function(index, parameter) {
        //TODO:
        console.log('parameter : ');
        console.log('parameter.getName() : ', parameter.getName());
        console.log('parameter.getCurrentValue() : ', parameter.getCurrentValue());
        console.log('parameter.getDataType() : ', parameter.getDataType());
        console.log('parameter.getAllowableValuesType() : ', parameter.getAllowableValuesType());
        console.log('parameter.getAllowableValues() : ', parameter.getAllowableValues());
        console.log('parameter.getMinValue() : ', parameter.getMinValue());
        console.log('parameter.getMaxValue() : ', parameter.getMaxValue());
        console.log('parameter.getStepSize() : ', parameter.getStepSize());
        console.log('parameter.getDateStepPeriod() : ', parameter.getDateStepPeriod());
      });
    };
    var onFault = function() {
      //TODO:
    };
    workbook
      .getParametersAsync()
      .then(onSuccess, onFault);
  }
};
try {
  viz = new tableau.Viz(placeholderDiv, url, options);
} catch(e) {
  //TODO:
}

上記のように、ワークブックからパラメータ情報を取得することができます。

Parameter インスタンスから取得できる情報

Parameter インスタンスには、パラメータ編集で設定できる各項目の値が含まれており、それぞれの項目に対応した下記 get... メソッドを使用することで取得することが可能です。

メソッド名	型	説明
getName()	string	名前
getCurrentValue()	DataValue	パラメータの現在値
getDataType()	ParameterDataType	Data Type 値 ( Float、Integer、String、Boolean、Date、Datetime のいずれか )
getAllowableValuesType()	ParameterAllowableValuesType	Allowable values 値 ( ALL、LIST、RANGE のいずれか )
getAllowableValues()	DataValue[]	getDataType が List である場合に取得できる値の配列
getMinValue()	DataValue	getAllowableValuesType が Range である場合、これにより認められる「最小値 (包含) 」が定義される ( それ以外の場合は未定義または NULL)
getMaxValue()	DataValue	getAllowableValuesType が Range である場合、これにより認められる「最大値 (包含) 」が定義される ( それ以外の場合は未定義または NULL)
getStepSize()	Number	getAllowableValuesType が Range の場合、これによりパラメータ UI コントロール スライダーで使用されるステップ サイズが定義される ( それ以外の場合は未定義または NULL)
getDateStepPeriod()	PeriodType	getAllowableValuesType が Range、および getDataType が Date や Datetime の場合、これによりパラメータ UI コントロール スライダーで使用されるステップ期間が定義される ( それ以外の場合は未定義または NULL)

パラメータ情報の変更

workbook.changeParameterValueAsync(name: string, value: object) メソッドを使用することで任意のパラメータの値を変更することができます。

ただし、設定値はパラメータと同じデータ型で、値の許容範囲内である必要があります。

サンプル

Tableau Public の Authors Featured ( オススメ著者 ) である Chad Skelton 氏のサンプルを拝借して、『カナダ人の年齢別人口推移グラフのパラメータを外部から変更するサンプル』を作成してみました。( デフォルト値である 50 を 36 に変更させるサンプルです )

上記サンプルでは以下のようにパラメータ情報を取得することができます。

parameter.getName() :  YourAge
parameter.getCurrentValue() :  Object {value: 50, formattedValue: "50"}
parameter.getDataType() :  integer
parameter.getAllowableValuesType() :  range
parameter.getAllowableValues() :  null
parameter.getMinValue() :  Object {value: 1, formattedValue: "1"}
parameter.getMaxValue() :  Object {value: 99, formattedValue: "99"}
parameter.getStepSize() :  1
parameter.getDateStepPeriod() :  null

このパラメータを変更するときには…

workbook
  .changeParameterValueAsync('YourAge', 36)
  .then(function(updateParameter) {
    console.log('updateParameter : ', updateParameter);
  });

…と記述します。

まとめ

Tableau JavaScript API におけるパラメータの取り扱いについて触れてみました。作成した Tabelau ビューのパラメータ情報を正しく意識しないと操作することはできませんが、過去に紹介したフィルター、マークなどと根本的な記法はほぼ同じです。ビューの内部に UI を置きたくない場合や、カスタマイズ性にこだわる場合にこれらの機能は役立つと考えられます。