טיפול באירועים

בדף הזה מוסבר איך להאזין לאירועים שמופעלים על ידי תרשים ולטפל בהם.

תוכן עניינים

1. סקירה כללית
2. הרשמה לאירוע וטיפול בו
3. אחזור פרטי האירוע
4. האירוע בוחרים
5. האירוע מוכן
6. האירוע שגיאה
7. דוגמה לטיפול באירועים

סקירה כללית

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

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

יש אירוע אחד שצריך להפעיל כל תרשים שניתן לבחירה: האירוע שנבחר. עם זאת, ההתנהגות והמשמעות של האירוע הזה מוגדרות בכל תרשים.

חשוב לציין שהאירועים בתרשים הם נפרדים ונפרדים מאירועי ה-DOM הרגילים.

הרשמה לאירוע וטיפול בו

כדי לרשום את הגורמים המטפלים באירועים, צריך לקרוא ל-google.visualization.events.addListener() או ל-addOneTimeListener() עם שם התרשים שחושף את האירוע, שם המחרוזת של האירוע שרוצים להאזין לו ושם הפונקציה שצריך לקרוא כשהאירוע הזה מופעל. הפונקציה צריכה לקבל פרמטר יחיד שהוא האירוע שהופעל. האירוע הזה יכול לכלול מידע מותאם אישית על האירוע, כמו שמתואר במסמכי התיעוד של התרשים.

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

בקטע הקוד הבא מוצגת תיבת התראה בכל פעם שמשתמש לוחץ על שורה בטבלה:

// Create a table chart on your page.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

// Every time the table fires the "select" event, it should call your
// selectHandler() function.
google.visualization.events.addListener(table, 'select', selectHandler);

function selectHandler(e) {
  alert('A table row was selected');
}

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

אפשר גם להעביר הגדרת פונקציה, כפי שמוצג כאן:

// Pass in a function definition.
google.visualization.events.addListener(orgchart, 'select', function() {
  table.setSelection(orgchart.getSelection());
});

אחזור פרטי אירוע

בדרך כלל, אירועים חושפים מידע בשתי דרכים: על ידי העברת מידע לפונקציית ה-handler כפרמטר, או על ידי הוספת מידע לאובייקט גלובלי. אם המידע חושף את האירוע ואיך האירוע חשוף, צריך לתאר זאת במסמכי התיעוד של התרשים הזה. כך מאחזרים את שני סוגי המידע:

פרטי האירוע שמועברים ל-handler

אם התרשים מעביר נתונים כפרמטר לפונקציית הטיפול, צריך לאחזר אותם כפי שמוצג כאן:

// google.visualization.table exposes a 'page' event.
google.visualization.events.addListener(table, 'page', myPageEventHandler);
...
function myPageEventHandler(e) {
  alert('The user is navigating to page ' + e['page']);
}

לפרמטר שמועבר ל-handler יהיה מאפיין שצריך לתעד עבור התרשים. לדוגמה של תרשים שחושף את פרטי האירועים בצורה הזו, אפשר לראות את אירוע הדף של התרשים Table.

פרטי אירועים שמועברים לאובייקט גלובלי

חלק מהאירועים משנים מאפיין של אובייקט גלובלי, ואפשר לבקש אותם לאחר מכן. דוגמה נפוצה לאירוע הזה היא האירוע Select, שמופעל כשמשתמש בוחר חלק בתרשים. במקרה כזה, הקוד חייב לקרוא לפונקציה getSelection() בתרשים כדי ללמוד מהי הבחירה הנוכחית. מידע נוסף ניתן לגבי האירוע שנבחר למטה.

// orgChart is my global orgchart chart variable.
google.visualization.events.addListener(orgChart, 'select', selectHandler);
...
// Notice that e is not used or needed.
function selectHandler(e) {
  alert('The user selected' + orgChart.getSelection().length + ' items.');
  

האירוע Select

כפי שצוין קודם, כל תרשים שאפשר לבחור צריך להפעיל אירוע "select" שפועל באופן רגיל כדי לאפשר לכם לאחזר את הערכים של הפריט שנבחר בתרשים. (עם זאת, אין דרישה מוחלטת לכך שתרשים יתנהג בצורה הזו, אבל חשוב לבדוק את התיעוד של התרשים).

באופן כללי, תרשימים שחושפים את האירוע "select" מתוכננים לפי המפרטים הבאים:

• האירוע שנבחר לא מעביר מאפיינים או אובייקטים ל-handler (ה-handler של הפונקציה לא אמור לצפות שפרמטרים כלשהם יועברו אליו).
• התרשים אמור לחשוף את השיטה getSelection(), שמחזירה מערך אובייקטים שמתאר את רכיבי הנתונים שנבחרו. לאובייקטים האלה יש את המאפיינים row ו-column. row ו-column הם האינדקסים של השורות והעמודות של הפריט שנבחר ב-DataTable. (אירועי בחירה מתארים את הנתונים הבסיסיים בתרשים, ולא את רכיבי ה-HTML בתרשים). כדי לקבל את הנתונים של הפריט שנבחר, צריך להפעיל את הפונקציה DataTable.getValue() או getFormattedValue().
  אם מציינים גם את row וגם את column, הרכיב שנבחר הוא תא. אם ציינת רק row, הרכיב שנבחר הוא שורה. אם מציינים רק column, הרכיב שנבחר הוא עמודה.
• התרשים צריך לחשוף את השיטה setSelection(selection) כדי לשנות את הבחירה בטבלה הבסיסית ולבחור את הנתונים המתאימים בתרשים. הפרמטר selection הוא מערך שדומה למערך getSelection(), שבו כל רכיב הוא אובייקט עם המאפיינים row ו-column. המאפיין row מגדיר את האינדקס של השורה שנבחרה ב-DataTable, והמאפיין column מגדיר את האינדקס של העמודה שנבחרה ב-DataTable. כשמתבצעת קריאה לשיטה הזו, התרשים אמור לציין באופן חזותי מהי הבחירה החדשה. ההטמעה של setSelection() לא אמורה להפעיל אירוע Select.
  אם מציינים גם את row וגם את column, הרכיב שנבחר הוא תא. אם ציינת רק row, הרכיב שנבחר הוא שורה. אם מציינים רק column, הרכיב שנבחר הוא עמודה.

כמה נקודות שכדאי לשים לב אליהן:

• התרשים עשוי להתעלם מחלק מהבחירה. לדוגמה, טבלה שיכולה להציג רק שורות נבחרות יכולה להתעלם מאלמנטים של תאים או עמודות בהטמעה של setSelection).
• יכול להיות שחלק מהתרשימים לא יפעילו אירוע Select, ויכול להיות שחלק מהתרשימים תומכים רק בבחירת שורה שלמה או בבחירת עמודה כולה. התיעוד של כל תרשים מגדיר את האירועים והשיטות שבהם הוא תומך.
• אופן הבחירה בכמה משחקים בו-זמנית מטופל באופן שונה בתרשימים שונים (חלקם אפילו לא מאפשרים זאת).
• כדי לקרוא את הנתונים שנבחרו, צריך להפעיל את DataTable.getValue() ב-handler. הדרך הפשוטה ביותר להפעיל את האפשרות הזו היא להגדיר את האובייקט DataTable כגלובלי.

בדוגמה הבאה תופיע תיבת התראות עם רכיבי הטבלה שנבחרו, כשנבחר רכיב של תרשים טבלה:

הערה: תרשים הטבלה מפעיל רק אירועים של בחירת שורה. עם זאת, הקוד הוא כללי ואפשר להשתמש בו באירועים של בחירת שורה, עמודות ותאים.

זהו קוד ה-handler של הדוגמה הזו:

// Create our table.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

// Add our selection handler.
google.visualization.events.addListener(table, 'select', selectHandler);

// The selection handler.
// Loop through all items in the selection and concatenate
// a single message from all of them.
function selectHandler() {
  var selection = table.getSelection();
  var message = '';
  for (var i = 0; i < selection.length; i++) {
    var item = selection[i];
    if (item.row != null && item.column != null) {
      var str = data.getFormattedValue(item.row, item.column);
      message += '{row:' + item.row + ',column:' + item.column + '} = ' + str + '\n';
    } else if (item.row != null) {
      var str = data.getFormattedValue(item.row, 0);
      message += '{row:' + item.row + ', column:none}; value (col 0) = ' + str + '\n';
    } else if (item.column != null) {
      var str = data.getFormattedValue(0, item.column);
      message += '{row:none, column:' + item.column + '}; value (row 0) = ' + str + '\n';
    }
  }
  if (message == '') {
    message = 'nothing';
  }
  alert('You selected ' + message);
}

האירוע מוכן

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

באופן כללי, תרשימים שחושפים את האירוע Ready (מוכן) מעוצבים לפי המפרטים הבאים:

• האירוע המוכן לא מעביר מאפיינים ל-handler (ה-handler של הפונקציה לא אמור לצפות שפרמטרים כלשהם יועברו אליו).
• התרשים אמור להפעיל את האירוע המוכן אחרי שהתרשים מוכן לאינטראקציה. אם השרטוט של התרשים הוא אסינכרוני, חשוב שהאירוע יופעל כשניתן לקרוא בפועל לשיטות אינטראקציה, ולא רק כשה-method draw מסתיימת.
• צריך להוסיף אוזן לאירוע הזה לפני קריאה ל-method draw(), כי אחרת, יכול להיות שהאירוע יופעל לפני הגדרת המאזינים, והוא לא יוקלט.
• אם תקראו לשיטות אינטראקציה לפני שהאירוע המוכן מופעל, השיטות האלה לא יפעלו כמו שצריך.

המוסכמה היא שתרשימים שלא מפעילים אירוע "מוכן" מוכנים לאינטראקציה מיד אחרי שה-method draw מסתיימת ומחזירה למשתמש את הבקרה. אם התרשים כן מפעיל אירוע מוכן, צריך להמתין עד שהוא ייפסל לפני שמפעילים אותו בשיטות שונות, כמו בדוגמה הבאה:

google.visualization.events.addListener(tableChart, 'ready', myReadyHandler);

התחביר של מטפל האירועים מוכן

function myReadyHandler(){...}

הגורם המטפל באירועים המוכן לא מועבר לאף פרמטר.

האירוע שגיאה

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

אפשר להשתמש בפונקציות העזרה של goog.visualization.errors כדי להציג למשתמש שגיאות בצורה חלקה.

תחביר של מטפל באירועים של שגיאה

function myErrorHandler(err){...}

צריך להעביר את הגורם המטפל באירועים של שגיאות לאובייקט עם החברים הבאים:

• id [חובה] – המזהה של רכיב ה-DOM שמכיל את התרשים, או הודעת שגיאה שמוצגת במקום התרשים אם לא ניתן לעבד אותו.
• message [חובה] – מחרוזת של הודעה קצרה שמתארת את השגיאה.
• detailedMessage [אופציונלי] – הסבר מפורט של השגיאה.
• options [אופציונלי] – אובייקט שמכיל פרמטרים מותאמים אישית שמתאימים לשגיאה הזו ולסוג התרשים הזה.

דוגמה לטיפול באירועים

הדוגמה הבאה ממחישה גם את getSelection() וגם את setSelection(). היא מסנכרנת את הבחירה בין שני תרשימים שמשתמשים באותה טבלת נתונים. יש ללחוץ על אחד מהתרשימים כדי לסנכרן את הבחירה בתרשים האחר.

// Create our two charts.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, {});

var orgchart = new google.visualization.OrgChart(document.getElementById('org_div'));
orgchart.draw(data, {});

// When the table is selected, update the orgchart.
google.visualization.events.addListener(table, 'select', function() {
  orgchart.setSelection(table.getSelection());
});

// When the orgchart is selected, update the table chart.
google.visualization.events.addListener(orgchart, 'select', function() {
  table.setSelection(orgchart.getSelection());
});

כדי לראות את הבחירה בפעולה, תוכלו ללחוץ על התרשימים הבאים בשורות בטבלה או ברכיבי תרשים: