グラフの種類の作成

このページでは、独自のタイプのグラフを開発し、ユーザーが使用できるようにする方法について説明します。

視聴者

このページは、グラフの使用ページをお読みいただいていることを前提としています。また、JavaScript とオブジェクト指向プログラミングに精通していることを前提としています。ウェブ上に多数ある JavaScript チュートリアルも参考にしてください。

グラフの作成

グラフは、作成した JavaScript ライブラリを介してユーザーに公開されます。グラフ ライブラリを作成する手順は次のとおりです。

1. コードの名前空間を選択します。他のページでコードがホストされるため、名前が競合しないようにする必要があります。
2. グラフ オブジェクトを実装します。以下を公開する JavaScript オブジェクトを実装します。
   • コンストラクタ
   • コンストラクタに渡された DOM 要素内にオブジェクトを描画する draw() メソッド。
   • クライアントが使用するその他のオプションの標準メソッド（getSelection() など）
   • クライアントに公開するカスタム メソッド。
3. （省略可）クライアントが捕捉するイベントを実装します。
4. グラフのドキュメントを作成します。文書化しないと、おそらく埋め込みできません。
5. グラフをグラフ ギャラリーに投稿します。

名前空間を選択

グラフは、他のグラフや他の無関係な JavaScript をホストするページに埋め込むことができます。他のコードや CSS クラス名と名前が競合しないように、グラフのコードには固有の名前空間を選択する必要があります。名前空間には、スクリプトをホストするために使用する URL を使用することをおすすめします（WWW と拡張機能は除きます）。たとえば、グラフが www.example.com に投稿される場合は、一意の名前空間として example を使用します。で区切られた接尾辞を追加できます。マークを使用してグラフをさらにグループ化できます（Google のすべてのグラフには google.visualization という名前空間があります）。この名前空間オブジェクトを使用して、グラフ オブジェクトと、必要に応じてグローバル変数を保存します。

以下に、MyTable というグラフクラスと必要なグローバル変数を保持する名前空間オブジェクトを作成する例を示します。

// Namespace, implemented as a global variable.
var example = {};

// MyTable class constructor.
example.MyTable = function(container) {
  // ...
}

// MyTable.draw() method.
example.MyTable.prototype.draw = function(data, options) {
  // ...
}

CSS の競合の回避

CSS を使用する場合は、ページ上の他のグラフに影響する可能性がある CSS ルールを作成しないようにしてください。たとえば、td {color: blue;} などのルールは、グラフ内だけでなく、ページ上の他の <td> 要素にも影響するため、使用しないことを強くおすすめします。これに対処する 1 つの方法は、グラフ全体をクラス名の <div> で囲み、すべての CSS ルールがそのクラス名を持つ要素の子孫の要素にのみ適用されるようにすることです。たとえば、次の CSS ルールは、クラス名「example」の要素を祖先とする <td> 要素にのみ影響します。

td.example {color: blue;}

その後、次のようにしてグラフを <div> でラップできます。

<div class="example">
  ...
</div>

グラフの実装

グラフは、リファレンス セクションで説明されている標準メソッドを公開する JavaScript オブジェクトとして実装する必要があります。必須のメソッドは、コンストラクタと draw() の 2 つです。 グラフに適した追加のメソッドをユーザーに公開することもできます。ただし、使いやすいほどよいということを忘れないでください。

コンストラクタ

グラフは、単一のパラメータ（グラフを描画する DOM 要素）を受け取る単一のコンストラクタを公開する必要があります。通常、グラフは後で使用できるように、この要素のローカルコピーをコンストラクタに保存します。

function example.MyTable(container) {
  this.container = container
}

draw() メソッド

グラフクラスには、グラフクラスのプロトタイプで定義したメソッド draw() が必要です。draw() メソッドは、次の 2 つのパラメータを受け取ります。

1. 表示するデータを保持する DataTable。
2. グラフの名前/値オプションのマップ（省略可）。オプションの名前と値の型は、特定のグラフに対してユーザーが定義します。たとえば、以下の Hello チャートの例では、ブール値型の「showLineNumber」というオプションをサポートしています。ユーザーが特定のオプションの値を渡さない場合に備えて、各オプションでデフォルト値をサポートする必要があります。このパラメータは省略可能です。ユーザーがこのパラメータを渡さなかった場合に、すべてのデフォルト値を使用するように準備しておいてください（詳細）。

example.MyTable.prototype.draw = function(data, options) {
  // Process data and options and render output into the container element.
  ...
}

Hello Chart!

次に、DataTable データを HTML テーブルとして表示する簡単なグラフを示します。

実装コードは次のとおりです。

// Declare a unique namespace.
var example = {};

// Class constructor. Parameter container is a DOM elementon the client that
// that will contain the chart.
example.MyTable = function(container) {
  this.containerElement = container;
}

// Main drawing logic.
// Parameters:
//   data is data to display, type google.visualization.DataTable.
//   options is a name/value map of options. Our example takes one option.
example.MyTable.prototype.draw = function(data, options) {

  // Create an HTML table
  var showLineNumber = options.showLineNumber; // Boolean configuration option.

  var html = [];
  html.push('<table border="1">');

  // Header row
  html.push('<tr>');
  if (showLineNumber) {
    html.push('<th>Seq</th>');
  }
  for (var col = 0; col < data.getNumberOfColumns(); col++) {
    html.push('<th>' + this.escapeHtml(data.getColumnLabel(col)) + '</th>');
  }
  html.push('</tr>');

  for (var row = 0; row < data.getNumberOfRows(); row++) {
    html.push('<tr>');
    if (showLineNumber) {
      html.push('<td align="right">', (row + 1), '</td>');
    }

    for (var col = 0; col < data.getNumberOfColumns(); col++) {
      html.push(data.getColumnType(col) == 'number' ? '<td align="right">' : '<td>');
      html.push(this.escapeHtml(data.getFormattedValue(row, col)));
      html.push('</td>');
    }
    html.push('</tr>');
  }
  html.push('</table>');

  this.containerElement.innerHTML = html.join('');
}

// Utility function to escape HTML special characters
example.MyTable.prototype.escapeHtml = function(text) {
  if (text == null)
    return '';
  return text.replace(/&/g, '&').replace(/</g, '<')
      .replace(/>/g, '>').replace(/"/g, '"');
}

ウェブページへのグラフの組み込み

前のグラフを使用するには、ブラウザからアクセスできる .js ファイルに保存します。 次のコードを保存し、<script> ソース パラメータを JavaScript ファイルを指すように変更します。

<html>
  <head>
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type="text/javascript" src="mytablevis.js"></script>
    <script type="text/javascript">
      google.charts.load("current");

      // Set callback to run when API is loaded
      google.charts.setOnLoadCallback(drawVisualization);

      // Called when the Chart API is loaded.
      function drawVisualization() {

        // Create and populate a data table.
        var data = new google.visualization.DataTable();
        data.addColumn('string', 'Task');
        data.addColumn('number', 'Daily Hours');
        data.addRows(5);
        data.setCell(0, 0, 'Work');
        data.setCell(0, 1, 11);
        // Add more data rows and cells here

        // Instantiate our table object.
        var vis = new example.MyTable(document.getElementById('mydiv'));

        // Draw our table with the data we created locally.
        vis.draw(data, {showLineNumber: true});
       }
   </script>
  <title>MyTable example page</title></head>
  <body>
    <div id="mydiv"></div>
    <p>This page demonstrates hosting a table visualization.</p>
  </body>
</html>

 

イベントを実装する

有用なイベント（タイマー イベント、クリックなどのユーザー開始イベントなど）をグラフで発生させたい場合は、イベントの詳細（名前、送信するプロパティなど）を指定して google.visualization.events.trigger 関数を呼び出す必要があります。詳細は [イベント] ページで確認できます。 イベント オブジェクトにプロパティを追加してイベントの詳細をクライアントに公開するか、グラフでなんらかの get...() メソッドを公開し、クライアントがそのメソッドを呼び出すことでイベントの詳細を取得できます。いずれの場合も、メソッドまたはイベント プロパティを適切に文書化してください。

グラフのドキュメントの作成

グラフを適切に文書化しないと、多くのユーザーが獲得されない可能性があります。以下の情報を必ず記録してください。

• サポートしているすべての方法を記載します。draw() メソッドはすべてのグラフに共通ですが、各グラフで独自のメソッドを追加できます。（コンストラクタが標準以外の動作をしない限り、おそらく文書化する必要はありません）。使用可能なメソッドの一覧については、リファレンス ページをご覧ください。
• draw() メソッドがサポートするすべてのオプションを記述します。これには、各オプションの名前、想定される値の型、デフォルト値が含まれます。
• トリガーするすべてのイベントを記述します。つまり、各イベントの名前とプロパティ、各イベントがトリガーされるタイミングを表します。
• クライアントの <script> include ステートメントで使用する必要があるグラフ ライブラリの URL をリストし、ドキュメントの URL を指定します。
• グラフの完全修飾名を入力します。
• サポートされているオプション、イベント、カスタム メソッドを備えたグラフの使用方法を示すサンプルページを作成します。
• グラフのデータポリシーを明確に説明します。ほとんどのグラフはブラウザ内でデータを処理しますが、グラフやマップの画像を作成する場合などのために、サーバーにデータを送信するグラフもあります。サーバーにデータを送信する場合:
  • 送信するデータを明確に定義します。
  • データがサーバーに保存される期間に注意してください。
  • データにアクセスできるエンティティを文書化します。たとえば、Company XYZ など。
  • データをログに記録するかどうかとその期間を指定します。

ドキュメントはグラフのコードと同じ場所にホストされます（下記のグラフをギャラリーに送信するをご覧ください）。

グラフをギャラリーに送信する

グラフを作成したら、送信して、ギャラリーの [その他のグラフ] セクションに投稿します。チャートを提出する場合は、不正なソフトウェアの作成やユーザーデータの不正使用について同意しない Google との契約に署名していただく必要があります。ギャラリーは、Google が作成した、またはレビューしたグラフへのポインタのリストです。実際の JavaScript ライブラリとドキュメントをホストするか、Google にライブラリとドキュメントのホストを任せることもできます。ギャラリーに投稿する際にグラフをホストするかどうかを指定します。

トラブルシューティング

コードが機能しない場合は、次のアプローチを参考にしてください。

• 入力ミスを探します。JavaScript では大文字と小文字が区別されることに注意してください。
• JavaScript デバッガを使用します。Firefox では、JavaScript コンソール、 Venkman Debugger、または Firebug アドオンを使用できます。IE では、 Microsoft Script デバッガを使用できます。
• Google Chart API のヘルプグループで検索してみてください。 疑問の答えとなる投稿が見つからない場合は、問題を実証するウェブページへのリンクと一緒に質問を投稿してください。

ローカライズ

さまざまな国のユーザーがグラフを使用することを想定している場合は、さまざまな言語や文化に合わせてローカライズされるようにグラフを設計することをおすすめします。最も基本的なローカライズは、ユーザーのブラウザ設定に応じて UI の標準テキスト文字列を翻訳することです。より高度なローカライズ方法としては、ローカライズ、または UI デザインに応じて数値形式を変更する方法があります。グラフをローカライズする場合は、グラフでサポートされている言語をドキュメントにリストし、よく使用される言語のデフォルト設定を指定します。また、言語が間違っている場合に備えて、グラフの UI に [言語を変更] ボタンを含めると便利です。ブラウザの言語を検出する一般的な方法は、Accept-Language HTML ヘッダーを調べることです。