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