Diagrammtypen erstellen

Auf dieser Seite wird beschrieben, wie Sie einen eigenen Diagrammtyp entwickeln und für Nutzer verfügbar machen.

Zielgruppe

Auf dieser Seite wird davon ausgegangen, dass Sie die Seite Diagramme verwenden gelesen haben. Außerdem wird davon ausgegangen, dass Sie mit JavaScript und objektorientierter Programmierung vertraut sind. Im Web sind viele JavaScript-Anleitungen verfügbar.

Diagramme erstellen

Diagramme werden dem Nutzer über eine von Ihnen erstellte JavaScript-Bibliothek angezeigt. So erstellen Sie eine Diagrammbibliothek:

  1. Wählen Sie einen Namespace für Ihren Code aus. Dein Code wird auf anderen Seiten gehostet. Versuche, Namenskonflikte zu vermeiden.
  2. Implementieren Sie das Diagrammobjekt. Implementieren Sie ein JavaScript-Objekt, das Folgendes verfügbar macht:
    • Ein Konstruktor
    • Eine draw()-Methode zum Zeichnen des Objekts innerhalb des an den Konstruktor übergebenen DOM-Elements
    • Alle anderen optionalen Standardmethoden, die von einem Client verwendet werden können, z. B. getSelection() und
    • Alle benutzerdefinierten Methoden, die Sie Ihren Clients zur Verfügung stellen möchten.
  3. [Optional] Implementieren Sie alle Ereignisse , die Sie auslösen möchten, damit der Client sie abfängt.
  4. Schreiben Sie die Dokumentation für Ihr Diagramm. Wenn du sie nicht dokumentierst, können Nutzer sie wahrscheinlich nicht einbetten.
  5. Posten Sie Ihr Diagramm in der Diagrammgalerie.

Tipp

  • Sie können die goog.visualization-API-Klassen- und -Methodendefinitionen herunterladen, um die automatische Vervollständigung in Ihrer IDE (Codeeditor) zu aktivieren. Laden Sie die Datei von http://www.google.com/uds/modules/gviz/gviz-api.js herunter und speichern Sie sie in Ihrem Projekt. Die meisten IDEs indexieren sie automatisch und aktivieren die automatische Vervollständigung, auch wenn Ihre IDE möglicherweise anders aussieht. Hinweis: Die Datei ist möglicherweise nicht immer aktuell. Auf der Referenzseite findest du die aktuelle API-Referenz.

Namespace auswählen

Das Diagramm kann auf einer Seite eingebettet werden, auf der andere Diagramme oder JavaScript ohne Bezug gehostet werden. Um Namenskonflikte mit anderen Code- oder CSS-Klassennamen zu vermeiden, sollten Sie für Ihren Diagrammcode einen eindeutigen Namespace auswählen. Eine gute Wahl für einen Namespace ist die URL, unter der Sie das Skript hosten (ohne den WWW und etwaige Erweiterungen). Wenn Ihr Diagramm beispielsweise unter www.beispiel.de veröffentlicht wird, würden Sie example als eindeutigen Namespace verwenden. Sie können zusätzliche Suffixe hinzufügen, die durch getrennt voneinander sind . markieren, um Ihr Diagramm weiter zu gruppieren. Alle Diagramme von Google haben den Namespace google.visualization. Verwenden Sie Ihr Namespace-Objekt zum Speichern Ihres Diagrammobjekts sowie aller globalen Variablen, die Sie möglicherweise benötigen.

Hier ist ein Beispiel für das Erstellen eines Namespace-Objekts mit einer Diagrammklasse namens MyTable sowie mit allen erforderlichen globalen Variablen:

// 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-Konflikte vermeiden

Wenn Sie CSS verwenden, achten Sie darauf, keine CSS-Regeln zu schreiben, die sich auf andere Diagramme auf der Seite auswirken können. Von einer Regel wie td {color: blue;} wird beispielsweise dringend abgeraten, da sie alle anderen <td>-Elemente auf der Seite betrifft, nicht nur im Diagramm. Eine Möglichkeit, dies zu vermeiden, besteht darin, das gesamte Diagramm in einen <div> mit einem Klassennamen aufzunehmen und alle Ihre CSS-Regeln nur auf Elemente anzuwenden, die Nachfolgerelemente eines Elements mit diesem Klassennamen sind. Die folgende CSS-Regel betrifft beispielsweise nur <td>-Elemente, die ein Element mit dem Klassennamen „example“ als Ancestor haben.

td.example {color: blue;}

Anschließend können Sie das Diagramm in <div> einschließen :

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

Diagramme implementieren

Du musst dein Diagramm als JavaScript-Objekt implementieren, das die im Abschnitt Referenz beschriebenen Standardmethoden umfasst. Die beiden erforderlichen Methoden sind die Konstruktor- und der remove()-Methode. Außerdem haben Sie die Möglichkeit, jedem Nutzer weitere Methoden zur Verfügung zu stellen, die für das Diagramm geeignet sind. Denken Sie daran: Je einfacher die Bedienung, desto besser.

Konstruktor

Das Diagramm sollte einen einzelnen Konstruktor enthalten, der einen einzelnen Parameter, ein DOM-Element, in das Sie das Diagramm zeichnen, annimmt. In der Regel wird in Diagrammen eine lokale Kopie dieses Elements zur späteren Verwendung im Konstruktor gespeichert:

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

Die Methode draw()

Für Ihre Diagrammklasse sollte die Methode draw() im Prototyp der Diagrammklasse definiert sein. Die Methode draw() akzeptiert zwei Parameter:

  1. Ein DataTable, das die anzuzeigenden Daten enthält.
  2. Eine optionale Zuordnung von Name/Wert-Optionen für Ihr Diagramm Die Namen und Werttypen der Optionen werden von Ihnen für das jeweilige Diagramm festgelegt. Im Beispiel „Hello Chart“ unten unterstützt das Diagramm beispielsweise eine Option namens „showLineNumber“ mit einem Wert vom Typ Boolesch. Sie sollten für jede Option einen Standardwert unterstützen, falls der Nutzer einen Wert für eine bestimmte Option nicht übergibt. Dieser Parameter ist optional. Sie sollten also auch darauf vorbereitet sein, alle Standardwerte zu verwenden, wenn der Nutzer diesen Parameter nicht übergibt (weitere Informationen).
example.MyTable.prototype.draw = function(data, options) {
  // Process data and options and render output into the container element.
  ...
}

Hallo Diagramm!

Dieses einfache Diagramm zeigt DataTable-Daten als HTML-Tabelle an:

Hier ist der Implementierungscode:

// 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, '"');
}

Diagramm in eine Webseite einfügen

Wenn Sie das vorherige Diagramm verwenden möchten, speichern Sie es in einer JS-Datei, auf die Sie über Ihren Browser zugreifen können. Speichern Sie dann den folgenden Code und ändern Sie den <script>-Quellparameter so, dass er auf Ihre JavaScript-Datei verweist:

<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>

 

Ereignisse implementieren

Wenn im Diagramm nützliche Ereignisse (z. B. Timer-Ereignisse oder vom Nutzer initiierte Ereignisse wie Klicks) ausgelöst werden sollen, müssen Sie die Funktion google.visualization.events.trigger mit den Details des Ereignisses aufrufen (Name, zu sendende Properties usw.). Weitere Informationen finden Sie auf der Seite Ereignisse. Sie können entweder die Ereignisdetails für den Client freigeben, indem Sie dem Ereignisobjekt Properties hinzufügen, oder Sie können eine get...()-Methode in Ihrem Diagramm bereitstellen, die vom Client aufgerufen werden kann, um die Ereignisdetails abzurufen. In beiden Fällen solltest du deine Methoden oder Ereignis-Properties gut dokumentieren.

Diagramm dokumentieren

Wenn Sie das Diagramm nicht ordnungsgemäß dokumentieren, erhalten Sie wahrscheinlich nicht viele Nutzer. Achten Sie darauf, Folgendes zu dokumentieren:

  • Beschreiben Sie alle unterstützten Methoden. Die Methode draw() ist für alle Diagramme gleich, aber jedes Diagramm kann seine eigenen zusätzlichen Methoden unterstützen. Möglicherweise müssen Sie den Konstruktor nur dokumentieren, wenn er nicht dem Standardverhalten entspricht. Eine Liste der erwarteten Methoden finden Sie auf der Referenzseite.
  • Beschreiben Sie alle Optionen, die Ihre Methode draw() unterstützt. Dazu gehören der Name der einzelnen Optionen, der erwartete Werttyp und sein Standardwert.
  • Beschreiben Sie alle Ereignisse, die Sie auslösen. Das sind der Name und die Eigenschaften jedes Ereignisses und wann jedes Ereignis ausgelöst wurde.
  • Listen Sie die URL Ihrer Diagrammbibliothek auf, die in der <script>-Include-Anweisung verwendet werden soll, und geben Sie die URL für Ihre Dokumentation an.
  • Geben Sie dem voll qualifizierten Namen das Diagramm an.
  • Erstellen Sie Beispielseiten, die die Verwendung des Diagramms mit den unterstützten Optionen, zugehörigen Ereignissen und benutzerdefinierten Methoden veranschaulichen.
  • Beschreiben Sie die Datenrichtlinie Ihres Diagramms klar. In den meisten Diagrammen werden die Daten im Browser verarbeitet. Einige senden sie jedoch an einen Server, z. B. um ein Bild eines Diagramms oder einer Karte zu erstellen. Wenn Sie Daten an einen Server senden:
    • Legen Sie klar fest, welche Daten gesendet werden.
    • Beachten Sie, wie lange die Daten auf dem Server gespeichert werden.
    • Dokumentieren Sie, welche Entitäten Zugriff auf die Daten haben. Zum Beispiel: „Unternehmen XYZ“.
    • Geben Sie an, ob und wie lange die Daten protokolliert werden.

Die Dokumentation wird an der gleichen Stelle wie Ihr Diagrammcode gehostet (siehe Diagramm an die Galerie senden unten).

Nachdem Sie Ihr Diagramm erstellt haben, reichen Sie es ein und stellen Sie es im Abschnitt Zusätzliche Diagramme in unserer Galerie bereit. Wenn Sie ein Diagramm einreichen, müssen Sie eine Vereinbarung mit uns unterzeichnen, in der Sie verpflichtet sind, keine schädliche Software zu erstellen oder Nutzerdaten zu missbrauchen. Die Galerie ist nur eine Liste von Verweisen auf von uns erstellte oder geprüfte Diagramme. Sie können die tatsächliche JavaScript-Bibliothek und die Dokumentation auf Ihrer eigenen Website hosten. Alternativ können Sie sich die Bibliothek und die Dokumentation von Google hosten lassen. Gib an, ob wir dein Diagramm hosten möchten, wenn du es in der Galerie postest.

Fehlerbehebung

Wenn Ihr Code nicht funktioniert, können Sie die folgenden Lösungsansätze ausprobieren:

  • Suchen Sie nach Tippfehlern. Denken Sie daran, dass in JavaScript zwischen Groß- und Kleinschreibung unterschieden wird.
  • Verwenden Sie einen JavaScript-Debugger. In Firefox können Sie die JavaScript-Konsole, den Venkman-Debugger oder das Firebug-Add-on verwenden. In IE können Sie den Microsoft Script Debugger verwenden.
  • Durchsuchen Sie die Diskussionsgruppe für die Google Chart API. Wenn du keinen Beitrag findest, in dem deine Frage beantwortet wird, poste deine Frage in der Gruppe zusammen mit einem Link zu einer Webseite, auf der das Problem demonstriert wird.

Lokalisierung

Wenn Sie davon ausgehen, dass Ihr Diagramm von Nutzern in verschiedenen Ländern verwendet wird, sollten Sie Ihr Diagramm für verschiedene Sprachen und Kulturen lokalisieren. Die einfachste Lokalisierung besteht darin, die Standardtextstrings auf der Benutzeroberfläche gemäß den Browsereinstellungen des Nutzers zu übersetzen. Eine komplexere Lokalisierung wäre die Anpassung der Zahlenformate in Abhängigkeit von der Lokalisierung oder sogar dem Design der Benutzeroberfläche. Wenn Sie Ihr Diagramm lokalisieren möchten, geben Sie die in der Dokumentation unterstützten Sprachen an und legen Sie eine Standardeinstellung einer häufig verwendeten Sprache fest. Es kann auch sinnvoll sein, in die Benutzeroberfläche des Diagramms die Schaltfläche „Sprache ändern“ einzufügen, falls die Sprache falsch ist. Die am häufigsten verwendete Browsersprache wird im Accept-Language-HTML-Header angegeben.