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

Обзор

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!"

Метод инициализации

Передача объекта метода в createComponent дает вам доступ к прототипу вашего компонента, но не дает вам доступа к конструктору вашего компонента.

Чтобы решить эту проблему, при создании новых компонентов Embed API они автоматически проверяют наличие метода initialize . Если он найден, он будет вызван с теми же arguments которые были переданы конструктору. Вместо этого всю логику, которую вы обычно помещаете в конструктор, следует помещать в метод инициализации.

Вот пример, который устанавливает некоторые свойства по умолчанию при создании новых экземпляров 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.
});

Ждём готовности библиотеки

Фрагмент API внедрения загружает библиотеку и все ее зависимости асинхронно. Это означает, что такие методы, как createComponent не будут доступны сразу, и код, вызывающий такие методы, должен быть отложен до тех пор, пока все не будет загружено.

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> .

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