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

概要

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 メソッドで作成されたコンポーネントは、すべての組み込みコンポーネント（get、set、on、once、off、emit）で共有される基本メソッドを自動的に継承します。これにより、すべてのコンポーネントが一貫性があり、予測可能な方法で動作します。

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

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();
myComponentInstance.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() {
      // ...
    }
  });
});

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

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

読み込み順序が重要であるため、まず 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 など）のような依存関係が含まれる場合があります。このような依存関係を記述するかどうかはコンポーネントの作成者次第、依存関係が満たされるかどうかはコンポーネントのユーザー次第です。

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

概要