יצירת סוגי תרשימים

בדף הזה נסביר איך לפתח סוג תרשים משלכם ולהפוך אותו לזמין למשתמשים.

קהל

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

יצירת תרשים

התרשימים נחשפים למשתמש דרך ספריית JavaScript שאתם יוצרים. כדי ליצור ספריית תרשימים:

1. עליך לבחור מרחב שמות לקוד שלך. דפים אחרים יארחו את הקוד שלך. עליך לנסות למנוע התנגשויות בין שמות.
2. מטמיעים את אובייקט התרשים. מטמיעים אובייקט JavaScript שחושף את הפרטים הבאים:
   • בנאי,
   • שיטה draw() לשרטוט האובייקט בתוך רכיב ה-DOM שמועבר ל-constructor,
   • כל method סטנדרטי אופציונלי אחר שבו הלקוח יכול להשתמש, כמו getSelection(), ו-
   • כל שיטה מותאמת אישית שאתם רוצים לחשוף ללקוחות.
3. [אופציונלי] מטמיעים כל אירוע שרוצים להפעיל כדי שהלקוח יקליט.
4. כותבים את התיעוד של התרשים. אם לא יתבצע תיעוד, אנשים לא יוכלו להטמיע אותו.
5. מפרסמים את התרשים בגלריית התרשימים.

טיפ

• תוכלו להוריד את ההגדרות של המחלקה והשיטה goog.visualization של ה-API כדי להפעיל את ההשלמה האוטומטית בסביבת הפיתוח המשולבת (IDE) (עורך קוד). מורידים את הקובץ מהכתובת http://www.google.com/uds/modules/gviz/gviz-api.js ושומרים אותו בפרויקט. רוב סביבות הפיתוח המשולבות (IDE) יוסיפו אותן לאינדקס באופן אוטומטי ויאפשרו השלמה אוטומטית, אבל סביבת הפיתוח המשולבת עשויה להיות שונה. שימו לב שהקובץ לא תמיד יהיה עדכני; כדאי לעיין בדפי העזר כדי למצוא את חומרי העזר העדכניים ביותר של ה-API.

בחירת מרחב שמות

אפשר להטמיע את התרשים בדף שמארח תרשימים אחרים או JavaScript אחר שאינו קשור. כדי למנוע התנגשויות בין שמות של קוד או מחלקות אחרים של CSS, צריך לבחור מרחב שמות ייחודי לקוד התרשים. אפשרות טובה למרחב שמות היא כתובת ה-URL שבה תשתמשו לאירוח הסקריפט (ללא WWW וכל התוספים). לדוגמה, אם התרשים יפורסם בכתובת www.example.com, עליך להשתמש ב-example כמרחב השמות הייחודי. אפשר להוסיף עוד סיומות, ולהפריד ביניהן באמצעות . כדי לקבץ את התרשים עוד יותר (לכל התרשימים של Google מרחב השמות google.visualization). אפשר להשתמש באובייקט מרחב השמות כדי לאחסן את אובייקט התרשים ואת כל המשתנים הגלובליים הנדרשים.

הנה דוגמה ליצירת אובייקט של מרחב שמות כדי להחזיק מחלקה של תרשים בשם MyTable, וגם כל משתנה גלובלי שנדרש:

// Namespace, implemented as a global variable.
var example = {};

// MyTable class constructor.
example.MyTable = function(container) {
  // ...
}

// MyTable.draw() method.
example.MyTable.prototype.draw = function(data, options) {
  // ...
}

מניעת התנגשויות בין שירותי CSS

אם משתמשים ב-CSS, חשוב לא לכתוב כללי CSS שיכולים להשפיע על תרשימים אחרים בדף. לדוגמה, מומלץ מאוד לא להשתמש בכלל כמו td {color: blue;}, כי הוא ישפיע על כל רכיב <td> אחר בדף, ולא רק על התרשים. דרך אחת להתגבר על כך היא להקיף את כל התרשים ב-<div> בשם מחלקה, ולהגדיר שכל כללי ה-CSS יחולו רק על רכיבים שהם צאצאים של רכיב עם שם המחלקה הזה. לדוגמה, כלל ה-CSS הבא ישפיע רק על רכיבי <td> שכוללים רכיב עם שם המחלקה 'example' כהורה.

td.example {color: blue;}

לאחר מכן אפשר להקיף את התרשים ב-<div> באמצעות :

<div class="example">
  ...
</div>

הטמעת התרשים

צריך להטמיע את התרשים כאובייקט JavaScript שחושף את ה-methods הרגילות שמתוארות בקטע העזר. שתי השיטות הנדרשות הן ה-constructor והשיטות של pull() . אפשר גם לחשוף למשתמש שיטות נוספות שמתאימות לתרשים. עם זאת, חשוב לזכור שעדיף להשתמש באפליקציה בקלות רבה יותר.

הבונה

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

function example.MyTable(container) {
  this.container = container
}

השיטה draw()

במחלקת התרשים צריכה להיות מוגדרת method draw() באב הטיפוס של מחלקת התרשים. ה-method draw() מקבלת שני פרמטרים:

1. DataTable שמכיל את הנתונים להצגה.
2. מפה אופציונלית של אפשרויות שם/ערך לתרשים. אתם מגדירים את השמות וסוגי הערכים של האפשרויות בתרשים הספציפי. לדוגמה, בדוגמה Hello Chart, התרשים תומך באפשרות בשם 'showLineNumber' עם ערך מסוג Boolean. צריך לתמוך בערך ברירת מחדל לכל אפשרות, במקרה שהמשתמשים לא מעבירים ערך של אפשרות ספציפית. הפרמטר הזה הוא אופציונלי, לכן עליכם להיות מוכנים להשתמש בכל ערכי ברירת המחדל אם המשתמש לא מעביר את הפרמטר הזה (מידע נוסף).

example.MyTable.prototype.draw = function(data, options) {
  // Process data and options and render output into the container element.
  ...
}

שלום תרשים!

הנה תרשים פשוט שמציג נתונים של DataTable כטבלת HTML:

והנה קוד ההטמעה:

// Declare a unique namespace.
var example = {};

// Class constructor. Parameter container is a DOM elementon the client that
// that will contain the chart.
example.MyTable = function(container) {
  this.containerElement = container;
}

// Main drawing logic.
// Parameters:
//   data is data to display, type google.visualization.DataTable.
//   options is a name/value map of options. Our example takes one option.
example.MyTable.prototype.draw = function(data, options) {

  // Create an HTML table
  var showLineNumber = options.showLineNumber; // Boolean configuration option.

  var html = [];
  html.push('<table border="1">');

  // Header row
  html.push('<tr>');
  if (showLineNumber) {
    html.push('<th>Seq</th>');
  }
  for (var col = 0; col < data.getNumberOfColumns(); col++) {
    html.push('<th>' + this.escapeHtml(data.getColumnLabel(col)) + '</th>');
  }
  html.push('</tr>');

  for (var row = 0; row < data.getNumberOfRows(); row++) {
    html.push('<tr>');
    if (showLineNumber) {
      html.push('<td align="right">', (row + 1), '</td>');
    }

    for (var col = 0; col < data.getNumberOfColumns(); col++) {
      html.push(data.getColumnType(col) == 'number' ? '<td align="right">' : '<td>');
      html.push(this.escapeHtml(data.getFormattedValue(row, col)));
      html.push('</td>');
    }
    html.push('</tr>');
  }
  html.push('</table>');

  this.containerElement.innerHTML = html.join('');
}

// Utility function to escape HTML special characters
example.MyTable.prototype.escapeHtml = function(text) {
  if (text == null)
    return '';
  return text.replace(/&/g, '&').replace(/</g, '<')
      .replace(/>/g, '>').replace(/"/g, '"');
}

הכללת התרשים בדף אינטרנט

כדי להשתמש בתרשים הקודם, יש לשמור אותו בקובץ js .ניתן לגשת אליו מהדפדפן. לאחר מכן שומרים את הקוד הבא, ומשנים את פרמטר המקור <script> כך שיפנה לקובץ ה-JavaScript:

<html>
  <head>
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type="text/javascript" src="mytablevis.js"></script>
    <script type="text/javascript">
      google.charts.load("current");

      // Set callback to run when API is loaded
      google.charts.setOnLoadCallback(drawVisualization);

      // Called when the Chart API is loaded.
      function drawVisualization() {

        // Create and populate a data table.
        var data = new google.visualization.DataTable();
        data.addColumn('string', 'Task');
        data.addColumn('number', 'Daily Hours');
        data.addRows(5);
        data.setCell(0, 0, 'Work');
        data.setCell(0, 1, 11);
        // Add more data rows and cells here

        // Instantiate our table object.
        var vis = new example.MyTable(document.getElementById('mydiv'));

        // Draw our table with the data we created locally.
        vis.draw(data, {showLineNumber: true});
       }
   </script>
  <title>MyTable example page</title></head>
  <body>
    <div id="mydiv"></div>
    <p>This page demonstrates hosting a table visualization.</p>
  </body>
</html>

 

הטמעת האירועים

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

תיעוד התרשים

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

• תיאור של כל השיטות שאתם תומכים בהן. השיטה draw() נפוצה לכל התרשימים, אבל כל תרשים יכול לתמוך בשיטות נוספות משלו. (סביר להניח שאין צורך לתעד את ה-constructor, אלא אם יש לו התנהגות לא סטנדרטית.) רשימה של השיטות הצפויות מופיעה בדף העזר.
• עליך לתאר את כל האפשרויות ששיטת draw() שלך תומכת בהן. המידע הזה כולל את השם של כל אפשרות, את סוג הערך הצפוי ואת ערך ברירת המחדל שלו.
• תארו את כל האירועים שאתם מפעילים. פירוש הדבר הוא השם והמאפיינים של כל אירוע, והמועד שבו כל אירוע מופעל.
• כאן צריך לרשום את כתובת ה-URL של ספריית התרשימים שבה צריך להשתמש בהצהרת ה-<script> של הלקוח, ולציין את כתובת ה-URL של המסמך.
• נותנים לתרשים את השם המוגדר במלואו.
• אפשר ליצור דפים לדוגמה שמדגימים איך להשתמש בתרשים יחד עם האפשרויות שהוא תומך בהן, האירועים שבו והשיטות המותאמות אישית.
• צריך לתאר בצורה ברורה את המדיניות של התרשים. רוב התרשימים מעבדים את הנתונים בדפדפן, אבל חלקם עשויים לשלוח נתונים לשרת, למשל כדי ליצור תמונה של תרשים או מפה. אם בכל זאת שולחים נתונים לשרת:
  • צריך להגדיר בבירור אילו נתונים יישלחו.
  • שימו לב למשך כמה זמן הנתונים יישמרו בשרת.
  • מסמך לאילו ישויות תהיה גישה לנתונים. לדוגמה, חברה XYZ וכו'.
  • לציין אם הנתונים יתועדו ולמשך כמה זמן.

המסמכים שלכם יתארחו באותו מקום שבו מתארח קוד התרשים (ראו שליחת התרשים לגלריה בהמשך).

שליחת התרשים לגלריה

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

פתרון בעיות

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

• מחפשים שגיאות הקלדה. חשוב לזכור ש-JavaScript היא שפה תלוית אותיות רישיות.
• שימוש בכלי לניפוי באגים של JavaScript. ב-Firefox, אפשר להשתמש במסוף JavaScript, ב- Vvenkman Debugger או בתוסף Firebug. באירלנד, אפשר להשתמש ב כלי לניפוי באגים של Microsoft Script.
• מחפשים בקבוצת הדיון של Google Chart API. אם לא מצאת פוסט שיענה על השאלה שלך, אפשר לפרסם את השאלה בקבוצה יחד עם קישור לדף אינטרנט שמדגים את הבעיה.

התאמה לשוק המקומי

אם אתם מצפים שהתרשים שלכם ישמש אנשים במגוון מדינות, מומלץ לעצב את התרשים כך שיהיה מותאם לשפות שונות ולתרבויות שונות. ההתאמה הבסיסית ביותר היא תרגום של מחרוזות הטקסט הרגילות בממשק המשתמש בהתאם להגדרות הדפדפן של המשתמש. התאמה מתקדמת יותר היא שינוי פורמטים של מספרים בהתאם לשוק המקומי, ואולי גם עיצוב של ממשק המשתמש. אם מחליטים להתאים לשוק המקומי את התרשים, צריך לפרט את השפות שבהן התרשים תומך בתיעוד ולספק הגדרת ברירת מחדל של שפה נפוצה. מומלץ גם לכלול לחצן 'שינוי שפה' בממשק המשתמש של התרשים, למקרה שזו טעות בשפה. הדרך הנפוצה לזהות את שפת הדפדפן היא לעיין בכותרת ה-HTML של Accept-Language.