דף זה תורגם על ידי Cloud Translation API.

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

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

קהל

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

יצירת תרשים

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

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

טיפ

ניתן להוריד את הגדרות ה-API והשיטה של goog.visualization כדי לאפשר השלמה אוטומטית ב-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 שחושף את השיטות הרגילות שמתוארות בקטע העזר. שתי השיטות הנדרשות הן 'הבנאי' ו-method() . כמו כן, אפשר לחשוף שיטות נוספות שמתאימות למשתמשים בתרשים. חשוב לזכור שקל יותר להשתמש בו.

הבנאי

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

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

השיטה `draw()`

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

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

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

מסמך התרשים

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

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

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

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

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

פתרון בעיות

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

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

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

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