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

סקירה כללית

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

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

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

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

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