Создание специальных компонентов

Обзор

Помимо встроенных компонентов 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();
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, как правило, размещаются в отдельных файлах 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), подготавливает разработчик компонента, а ответственность за работу с ними возлагается на его пользователя.