カスタム コンポーネントの作成

概要

Embed API には組み込みコンポーネントがいくつか用意されています。また、Embed API を使用すると、独自のコンポーネントを簡単に作成することができます。このドキュメントでは、新しいカスタム コンポーネントを作成する方法やアプリケーションにサードパーティのコンポーネントを含める方法について説明します。

カスタム コンポーネントの作成

カスタム Embed API コンポーネントを作成するには、gapi.analytics.createComponent を呼び出し、コンポーネント名とメソッド オブジェクトを渡します。

createComponent に渡された名前は、コンポーネントのコンストラクタ関数の名前になり、gapi.analytics.ext に格納されます。メソッド オブジェクトには、コンポーネントのプロトタイプに追加された必要な関数、またはプロパティを含める必要があります。

gapi.analytics.createComponent('MyComponent', {
  execute: function() {
    alert('I have been executed!');
  }
});

作成されたコンポーネントは、コンポーネント コンストラクタを使って new 演算子を呼び出すことにより使用することができます。

// Create a new instance of MyComponent.
var myComponentInstance = new gapi.analytics.ext.MyComponent();

// Invoke the `execute` method.
myComponentInstance.execute() // Alerts "I have been executed!"

initialize メソッド

createComponent にメソッド オブジェクトを渡すと、コンポーネントのプロトタイプにアクセスできるようになりますが、コンポーネントのコンストラクタへはアクセスできません。

この問題を解決するために、新しい Embed API コンポーネントは、作成されるときに initialize というメソッドが存在するかどうかを自動的に検索します。存在する場合、このメソッドは、コンストラクタに渡されたのと同じ arguments によって呼び出されます。通常ならコンストラクタに配置するすべてのロジックを、代わりに initialize メソッドに配置します。

新しい MyComponent インスタンスが作成されるときにデフォルトのプロパティをいくつか設定する例を次に示します。

gapi.analytics.createComponent('MyComponent', {
  initialize: function(options) {
    this.name = options.name;
    this.isRendered = false;
  }
});

var myComponentInstance = new gapi.analytics.ext.MyComponent({name: 'John'});
alert(myComponentInstance.name); // Alerts "John"
alert(myComponentInstance.isRendered); // Alerts false

継承されるメソッド

createComponent メソッドを使用して作成されたコンポーネントは、すべての組み込みコンポーネントで共有される基本メソッドgetsetononceoffemit)を自動的に継承します。これにより、すべてのコンポーネントは一貫性のある予測可能な方法で動作するようになります。

たとえば、コンポーネントでユーザーの認証が必要な場合に、継承されるイベント処理メソッドを使用することができます。

gapi.analytics.createComponent('MyComponent', {
  initialize: function() {
    this.isRendered = false;
  },
  execute: function() {
    if (gapi.analytics.auth.isAuthorized()) {
      this.render();
    }
    else {
      gapi.analytics.auth.once('success', this.render.bind(this));
    }
  },
  render: function() {
    if (this.isRendered == false) {

      // Render this component...

      this.isRendered = true;
      this.emit('render');
    }
  }
});

var myComponentInstance = new gapi.analytics.ext.MyComponent();

// Calling execute here will delay rendering until after
// the user has been successfully authorized.
myComponentInstance.execute();
myComponent.on('render', function() {
  // Do something when the component renders.
});

ライブラリの準備ができるまで待機

Embed API スニペットは、ライブラリとそのすべての依存関係を非同期で読み込みます。つまり、createComponent などのメソッドはすぐには使用できないため、このようなメソッドを呼び出すコードは、すべてが読み込まれるまで保留する必要があります。

Embed API で用意されている gapi.analytics.ready メソッドは、ライブラリが完全に読み込まれると呼び出されるコールバックを受け入れます。カスタム コンポーネントを作成する際は、必要なメソッドがすべて揃うまで実行されないようにコードを ready 関数内でラップします。

gapi.analytics.ready(function() {

  // This code will not run until the Embed API is fully loaded.
  gapi.analytics.createComponent('MyComponent', {
    execute: function() {
      // ...
    }
  });
});

独自のコンポーネントの作成方法の実践的な例については、Github で Embed API のデモをご覧ください。

サードパーティのコンポーネントの使用

通常、サードパーティの Embed API コンポーネントは、<script> タグを使用してページに含めることができる個々の JavaScript ファイルとしてパッケージ化されます。

読み込み順序が重要であるため、まず Embed API スニペットを含めた後、コンポーネント スクリプトとそのすべての依存関係を含めるようにしてください。

<!-- Include the Embed API snippet first. -->
<script>
(function(w,d,s,g,js,fjs){
  g=w.gapi||(w.gapi={});g.analytics={q:[],ready:function(cb){this.q.push(cb)}};
  js=d.createElement(s);fjs=d.getElementsByTagName(s)[0];
  js.src='https://apis.google.com/js/platform.js';
  fjs.parentNode.insertBefore(js,fjs);js.onload=function(){g.load('analytics')};
}(window,document,'script'));
</script>

<!-- Then include your components. -->
<script src="path/to/component.js"></script>
<script src="path/to/another-component.js"></script>

依存関係の管理

コンポーネントには、グラフ作成ライブラリ(d3.js など)や日付設定ライブラリ(moment.js など)のような依存関係が含まれる場合があります。このような依存関係を記述 するかどうかはコンポーネントの作成者次第、依存関係が満たされるかどうかは コンポーネントのユーザー次第です。