יצירת רכיבים בהתאמה אישית

סקירה

הטמעה של API כוללת כמה רכיבים מובנים ומאפשרת לכם ליצור בקלות רכיבים משלכם. במסמך הזה נסביר איך לפתח רכיב מותאם אישית חדש ואיך לכלול רכיבים של צד שלישי באפליקציה.

יצירת רכיב בהתאמה אישית

רכיבי API של הטמעה מותאמת אישית נוצרים על ידי קריאה ל-gapi.analytics.createComponent והעברת אובייקט ושיטות של רכיב.

השם שיועבר אל createComponent יהיה השם של פונקציית ה-constructor של הרכיב, והוא יאוחסן ב-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!"

שיטת האתחול

העברת אובייקט method אל createComponent נותנת גישה לאב הטיפוס של הרכיב, אבל לא מעניקה גישה לבונה הרכיב.

כדי לטפל בבעיה הזו, כשיוצרים רכיבים חדשים של embed API הם מחפשים באופן אוטומטי את הנוכחות של שיטה שנקראת initialize. אם יימצא, הוא יופעל עם אותו arguments שיועבר ל-constructor. את כל הלוגיקה שבדרך כלל מוסיפים ל-constructor, יש להשתמש בשיטת האתחול במקום זאת.

הדוגמה הבאה מגדירה כמה מאפייני ברירת מחדל כשיוצרים מכונות 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 לא יהיו זמינות באופן מיידי, וצריך לדחות קוד שמפעיל שיטות כאלה עד שהכול נטען.

הטמעה של 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() {
      // ...
    }
  });
});

שימוש ברכיבים של צד שלישי

רכיבי ממשק 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. מחבר הרכיב הוא זה שמתעד את יחסי התלות האלה, ובעל המשתמש של הרכיב כדי לוודא שהתלות מתקיימים.