WEBを駆使した売上UP/トータルサポートを提供　
株式会社パルムゲート

今回は前回作成した GoogleChartsHelper クラスの使い方を示す。

コントローラでのヘルパー定義

一番シンプルな定義はコントローラクラス内で GoogleCharts ヘルパーを指定するだけである。

なお、定義時にはオプションパラメータとして chartOptions 項目内に以下のものを指定できる。

loader

Google Charts 用のスクリプトをロードするための方法を指定する。値としては以下のものを利用可能。

• jquery (既定値): jquery の $(function () { ... }) でコードをロードする
• jquery-ready: jquery の $(document).ready(function () { ... }) でコードをロードする
• google: Google スクリプトの google.setOnLoadCallback(function () { ... }) でコードをロードする

このオプションは、Google Charts のレンダリング時のサイズを親コンテナサイズから取得するタイミングがずれて正しいサイズで表示されない場合に、使用しているツール/フレームワークと同じ方法を指定することでレンダリング情報取得タイミングを制御するために用いることができる。

使用例: コードローダーを既定値の jquery から jquery-ready に変更する

GoogleChartsHelper のメソッド詳細

GoogleChartsHelper::chartStart()

Google Charts を使用するために必要な準備をする。1ページに1回だけ呼び出す。複数回呼び出した場合の動作は保障されない。

GoogleChartsHelper::chartsEnd()

chartStart() 以降呼び出された Google Chart メソッドのために必要なコードを集約し、HtmlHelper::scriptBlock() メソッドで書き出す。各 Google Chart メソッド呼び出しはその場で直接コードを出力するのではなく、内部バッファに蓄積するのみ。蓄積されたコードを実際に出力するのがこの chartEnd() メソッドである。

1ページにつき1回だけ呼び出す。複数回呼び出した場合の動作は保障されない。

GoogleChartsHelper::chartAnnotation($jq_selector, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

アノーテーションチャートを出力する。

GoogleChartsHelper::chartArea($jq_selector, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

エリアチャートを出力する。

GoogleChartsHelper::chartBar($jq_selector, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

バーチャート (棒グラフ) を出力する。

GoogleChartsHelper::chartBubble($jq_selector, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

バブルチャートを出力する。

GoogleChartsHelper::chartCalendar($jq_selector, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

カレンダーチャートを出力する。

GoogleChartsHelper::chartCandlestick($jq_selector, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

キャンドルスティックチャート (ロウソク足チャート) を出力する。

GoogleChartsHelper::chartColumn($jq_selector, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

コラムチャートを出力する。

GoogleChartsHelper::chartCombo($jq_selector, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

コンボチャートを出力する。

GoogleChartsHelper::chartDiff($jq_selector, $type, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

$type 引数で指定した形式のチャートで差分チャートを出力する。

GoogleChartsHelper::chartGauge($jq_selector, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

ゲージチャートを出力する。

GoogleChartsHelper::chartGeo($jq_selector, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

ジオチャート (地域チャート) を出力する。

GoogleChartsHelper::chartHistogram($jq_selector, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

ヒストグラムを出力する。

GoogleChartsHelper::chartLine($jq_selector, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

ラインチャート (折れ線グラフ) を出力する。

GoogleChartsHelper::chartMap($jq_selector, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

マップチャート (Google Maps) を出力する。

GoogleChartsHelper::chartOrg($jq_selector, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

組織図を出力する。

GoogleChartsHelper::chartPie($jq_selector, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

パイチャート (円グラフ) を出力する。

GoogleChartsHelper::chartSankey($jq_selector, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

サンキーチャート (フローダイヤグラム) を出力する。

GoogleChartsHelper::chartScatter($jq_selector, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

スキャッターチャート (分散チャート) を出力する。

GoogleChartsHelper::chartSteppedArea($jq_selector, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

段階エリアチャートを出力する。

GoogleChartsHelper::chartTable($jq_selector, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

表組 (テーブル) を出力する。

GoogleChartsHelper::chartTimeline($jq_selector, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

タイムラインチャート (時系列図) を出力する。

GoogleChartsHelper::chartTreeMap($jq_selector, $data, $chart_options=array(), $handlers=array(), $helper_options=array())

ツリーマップ (樹状図) を出力する。

※通常想定する樹構造ではなく、矩形領域による階層構造を表現するチャート。

引数について

chartDiff() メソッド以外の各メソッドの引数は共通化されている。以下に各引数の概要を示す。

$jq_selector

必須。グラフ (チャート) を描画する領域を保持するコンテナ要素を特定するための jQuery セレクタ文字列。

(このヘルパーでは、描画領域を特定するのに jQuery セレクタが必須となっている点に注意。)

$data

必須。グラフに描画するデータ構造を表す配列。配列構造には2種類がある。

・簡易構造

配列の第0要素 (先頭要素； 0起算) がカラム情報、第1要素以降が表示データになる。各要素はさらに配列となっており、細かな表示情報を設定することも可能。表示要素は実際に表示するカラムデータの他、表示用のオプションデータ (スタイルなど) を記述することも可能。なお、第0要素が TRUE の時はカラム情報なしでデータのみが与えられたものとする。

例1:

array(
	array('Year', 'Sales', 'Expenses'), // カラム情報
	array('2004', 1000, 400),
	array('2005', 1170, 460),
	array('2006', 660, 1120),
	array('2007', 1030, 540),
);

例2: スタイル付カラム情報例

array(
	array('Element', 'Density', array('role' => 'style')), // カラム情報 (スタイル付)
	array('Copper', 8.94, '#b87333'),
	array('Silver', 10.49, 'silver'),
	array('Gold', 19.30, 'gold'),
	array('Platinum', 21.45, 'color: #e5e4e2'),
);

例3: カラム情報なし

array(
	TRUE,   // Treat first row as data as well.
	array('Mon', 20, 28, 38, 45),
	array('Tue', 31, 38, 55, 66),
	array('Wed', 50, 55, 77, 80),
	array('Wed', 50, 55, 77, 80),
	array('Fri', 68, 66, 22, 15),
);

・詳細構造

単純配列ではなく連想配列でカラム情報とデータを分離して指定する方法。$data['cols'] にはカラムの型など詳細情報を、$data['rows'] には表示データの詳細情報が記載される。

例1:

array(
	'cols' => array( // カラム詳細情報 (表示用カラムデータの型を明記)
		array('type' => 'date', 'id' => 'Date'),
		array('type' => 'number', 'id' => 'Won/Loss'),
	),
	'rows' => array( // 表示用データ
		array('2012-04-13', 37032),
		array('2012-04-14', 38024),
		array('2012-04-15', 38024),
		// …【以下略】…
	)
);

例2:

array(
	'cols' => array(
		array('string', 'Name'),
		array('number', 'Salary'),
		array('boolean', 'Full Time Employee'),
	),
	'rows' => array(
		array('Mike', array('v' => 10000, 'f' => '$10,000'), TRUE),
		array('Jim', array('v' => 8000, 'f' => '$8,000'), FALSE),
		array('Alice', array('v' => 12500, 'f' => '$12,500'), TRUE),
		array('Bob', array('v' => 7000, 'f' => '$7,000'), TRUE)
	),
);

データ型として解釈可能な値は下記の通り。

string

カラム値を文字列として処理するよう JavaScript コードを生成する。与えられた文字列に「'」 (シングルクォート) などが含まれる場合の動作は未規定。

date

カラム値を日付として処理し、JavaScript の Date コンストラクタ呼び出しを生成する。PHP の strtotime で処理できない日付 (1970-01-01 UTC 以前または 2038-01-19 UTC 以降など) も解釈可能な限り処理を試みる。生成した Date コンストラクタ呼び出しが動作するかどうかは JavaScript エンジンの実装に依存する。

number

カラム値を数値 (整数、固定小数点数または浮動小数点数) として JavaScript コードを生成する。

boolean

カラム値を論理値として解釈する。真偽は PHP の解釈に準ずる。PHP で「真」と解釈されるものは JavaScript の true、それ以外は JavaScript の false にマップされる。

なお、カラムデータ中の NULL は JavaScript の undefined にマップされる。これは、chart ツールでは空白値や「データ未定義」を表す場合 null ではなく undefined を使用するためである。

$chart_options

省略可。Google Chart の描画時のオプションを配列 (連想配列) として指定する。実際には Google Charts の draw メソッドの第2引数として渡される。省略時の値は空配列。

$handlers

省略可。チャートオブジェクトのイベントハンドラを指定する。省略時の値は空配列。

イベントハンドラはイベントトリガー名をキー、イベント処理コード文字列を値として指定する。指定したイベントハンドラは google.visualization.events.addListener() メソッドを利用してチャートオブジェクトに対し関連付ける。

例:

$this->GoogleCharts->chartPie('#pie-chart',
	array( /* some data */ ),
	array( /* some chart options here */ ),
	array(
		'select' => 'function (eventObj) { alert("chart is selected."); }';
	)
);

$helper_options

省略可。ヘルパー固有のオプションを「キー => 値」の組で指定した連想配列。省略時の値は空配列。現時点で利用可能はオプションキーは以下の通り。

callback

チャート生成後に何か処理 (タイマー処理など) が必要な場合に、文字列で JavaScript の無名関数コードを指定する。呼び出される関数には、1個のオブジェクトが引数として渡される。このオブジェクトには、以下の内容がハッシュ構造で与えられる。

data

チャートに与えられたデータオブジェクト

chart

使用したチャートオブジェクト

options

チャートに与えられたチャートオプションオブジェクト

以下の例では、チャート関連データのハッシュオブジェクトを引数 obj で受け取り、タイマーを使ってobj.data の内容を動的に変更する処理をしている。

array('callback' => 'function (obj) {
	setInterval(function () { obj.data.setValue(0, 1, 40+Math.round(60 * Math.random())); obj.chart.draw(obj.data, obj.options); }, 13000);
	setInterval(function () { obj.data.setValue(1, 1, 40+Math.round(60 * Math.random())); obj.chart.draw(obj.data, obj.options); }, 5000);
	setInterval(function () { obj.data.setValue(2, 1, 60+Math.round(20 * Math.random())); obj.chart.draw(obj.data, obj.options); }, 26000);
}');

なお、ユーザが記述する無名関数から外部の変数を参照してはならない。JavaScript の仕様上スコープ外変数の参照は可能だが、Google Charts ヘルパーが生成するコードがどのような内部変数を使用するかは規定されておらず、あるバージョンで動作した場合でも他のバージョンで同じ外部変数参照が許される (成功する) とは限らないからである。

この機能がないと上記のような chart オブジェクトやデータの事後操作が記述できない。しかしこの callback 機能はセキュリティホールにもなり得るので、将来廃止される可能性がある。

使用例

ビュー内での使用例を以下に示す。