Diagrammtypen erstellen

Auf dieser Seite wird beschrieben, wie Sie Ihren eigenen Diagrammtyp entwickeln und Nutzern zur Verfügung stellen.

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.

Diagramm 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. Du solltest versuchen, Namenskonflikte zu vermeiden.
2. Diagrammobjekt implementieren Implementieren Sie ein JavaScript-Objekt, das Folgendes bereitstellt:
   • Ein Konstruktor,
   • Eine draw()-Methode zum Zeichnen Ihres Objekts innerhalb des DOM-Elements, das an den Konstruktor übergeben wird
   • Sonstige optionale Standardmethoden, die ein Client verwenden kann, z. B. getSelection() und
   • Alle benutzerdefinierten Methoden, die Sie für Ihre Clients verfügbar machen möchten.
3. [Optional] Implementiere alle Ereignisse , die ausgelöst werden sollen, damit der Client sie abfangen kann.
4. Schreiben Sie die Dokumentation für Ihr Diagramm. Wenn Sie sie nicht dokumentieren, können andere sie wahrscheinlich nicht einbetten.
5. Posten Sie Ihr Diagramm in der Diagrammgalerie.

Namespace auswählen

Dein Diagramm kann auf einer Seite eingebettet werden, auf der andere Diagramme oder sonstiges JavaScript gehostet werden. Um Namenskonflikte mit anderen Code- oder CSS-Klassennamen zu vermeiden, sollten Sie einen eindeutigen Namespace für Ihren Diagrammcode auswählen. Eine gute Wahl für einen Namespace ist die URL, die Sie zum Hosten Ihres Skripts verwenden (abzüglich WWW und Erweiterungen). Wenn Ihr Diagramm beispielsweise unter www.beispiel.de veröffentlicht wird, verwenden Sie example als eindeutigen Namespace. Sie können weitere, durch getrennte Suffixe hinzufügen . gekennzeichnet, um das Diagramm weiter zu gruppieren (alle Diagramme von Google haben den Namespace google.visualization). Verwenden Sie das Namespace-Objekt zum Speichern des Diagrammobjekts sowie aller globalen Variablen, die Sie möglicherweise benötigen.

Im folgenden Beispiel wird ein Namespace-Objekt erstellt, das eine Diagrammklasse namens MyTable sowie alle erforderlichen globalen Variablen enthält:

// 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, dürfen Sie keine CSS-Regeln schreiben, die sich auf andere Diagramme auf der Seite auswirken können. Von einer Regel wie td {color: blue;} wird dringend abgeraten, da sie sich auf alle anderen <td>-Elemente auf der Seite auswirkt, nicht nur auf das Diagramm. Eine Möglichkeit, dies zu umgehen, besteht darin, Ihr gesamtes Diagramm in ein <div> mit einem Klassennamen einzuschließen und alle Ihre CSS-Regeln nur auf Elemente anzuwenden, die Nachfolger eines Elements mit diesem Klassennamen sind. Die folgende CSS-Regel gilt beispielsweise nur für <td>-Elemente mit einem Element mit dem Klassennamen „example“ als Ancestor.

td.example {color: blue;}

Dann können Sie Ihr Diagramm in einem <div> mit Folgendem zusammenfassen :

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

Diagramm implementieren

Du musst dein Diagramm als JavaScript-Objekt implementieren, das die im Referenzabschnitt beschriebenen Standardmethoden verfügbar macht. Die beiden erforderlichen Methoden sind der Konstruktor und diedraw()-Methoden. Sie können dem Nutzer auch weitere Methoden zur Verfügung stellen, die für das Diagramm geeignet sind. Bedenken Sie jedoch, dass nutzungsfreundlicher ist besser.

Der Konstruktor

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

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

Methode draw()

Ihre Diagrammklasse sollte im Prototyp Ihrer Diagrammklasse die Methode draw() haben. Die Methode draw() akzeptiert zwei Parameter:

1. Ein DataTable, der die anzuzeigenden Daten enthält.
2. Eine optionale Karte mit Namen/Wert-Optionen für Ihr Diagramm. Die Namen und Werttypen der Optionen werden von Ihnen für Ihr Diagramm definiert. Im „Hello-Diagramm“-Beispiel unten unterstützt das Diagramm beispielsweise die Option „showLineNumber“ mit einem Wert vom Typ „Boolesch“. Sie sollten für jede Option einen Standardwert unterstützen, falls der Nutzer keinen Wert für eine bestimmte Option übergibt. Dieser Parameter ist optional. Sie sollten also auch darauf vorbereitet sein, alle Standardwerte zu verwenden, falls 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 Chart!

Hier sehen Sie ein einfaches Diagramm mit DataTable-Daten als HTML-Tabelle:

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

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 Ihr Diagramm nützliche Ereignisse auslösen soll (z. B. Timer-Ereignisse oder vom Nutzer initiierte Ereignisse wie Klicks), müssen Sie die google.visualization.events.trigger-Funktion mit den Details des Ereignisses (Name, zu sendende Eigenschaften usw.) aufrufen. Weitere Informationen finden Sie auf der Seite Ereignisse. Sie können entweder Ihre Ereignisdetails für den Client freigeben, indem Sie dem Ereignisobjekt Eigenschaften hinzufügen, oder Sie können eine get...()-Methode eines bestimmten Typs in Ihrem Diagramm bereitstellen, mit der der Client diese Methode aufrufen kann, um die Ereignisdetails abzurufen. In beiden Fällen sollten Sie Ihre Methoden oder Ereigniseigenschaften gut dokumentieren.

Diagramm dokumentieren

Wenn Sie Ihr Diagramm nicht richtig dokumentieren, werden Sie wahrscheinlich nicht viele Nutzer gewinnen. Dokumentieren Sie Folgendes:

• Beschreiben Sie alle Methoden, die Sie unterstützen. 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 Ihren Konstruktor nicht dokumentieren, es sei denn, er weist ein nicht standardmäßiges Verhalten auf.) Eine Liste der erwarteten Methoden finden Sie auf der Referenzseite.
• Beschreiben Sie alle Optionen, die von Ihrer draw()-Methode unterstützt werden. Dazu gehören der Name jeder Option, der erwartete Werttyp und der Standardwert.
• Beschreiben Sie alle Ereignisse, die Sie auslösen. Dies bedeutet, dass der Name und die Eigenschaften jedes Ereignisses und wann jedes Ereignis ausgelöst wird.
• Geben Sie die URL Ihrer Diagrammbibliothek an, die in der <script>-Include-Anweisung des Clients verwendet werden soll, und geben Sie die URL zu Ihrer Dokumentation an.
• Geben Sie den voll qualifizierten Namen Ihres Diagramms an.
• Erstellen Sie Beispielseiten, auf denen die Verwendung des Diagramms mit den unterstützten Optionen, den Ereignissen und den benutzerdefinierten Methoden veranschaulicht wird.
• Beschreiben Sie klar die Datenrichtlinie Ihres Diagramms. Die meisten Diagramme verarbeiten die Daten im Browser. Einige senden jedoch möglicherweise Daten 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.
  • Achten Sie darauf, wie lange die Daten auf dem Server gespeichert werden.
  • Dokumentieren Sie, welche Entitäten Zugriff auf die Daten haben. Beispiel: Unternehmen XYZ usw.
  • Geben Sie an, ob und wie lange die Daten protokolliert werden.

Ihre Dokumentation wird am selben Ort wie Ihr Diagrammcode gehostet (siehe Diagramm an die Galerie senden unten).

Diagramm für die Galerie einreichen

Nachdem Sie Ihr Diagramm erstellt haben, reichen Sie es zur Veröffentlichung im Bereich „Zusätzliche Diagramme“ unserer Galerie ein. Wenn Sie ein Diagramm einreichen, müssen Sie eine Vereinbarung mit uns unterzeichnen, in der Sie zustimmen, keine schädliche Software zu erstellen oder Nutzerdaten zu missbrauchen. Die Galerie ist nur eine Liste von Verweisen auf Diagramme, die wir erstellt haben oder die wir geprüft haben. Sie können die eigentliche JavaScript-Bibliothek und -Dokumentation auf Ihrer eigenen Website hosten oder Google die Bibliothek und Dokumentation für Sie hosten lassen. Geben Sie an, ob Ihr Diagramm gehostet werden soll, wenn Sie es in der Galerie veröffentlichen.

Fehlerbehebung

Wenn Ihr Code nicht zu funktionieren scheint, finden Sie hier einige Ansätze, die Ihnen bei der Lösung Ihrer Probleme helfen könnten:

• 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.
• Suchen Sie im Diskussionsforum zur Google Chart API. Wenn Sie keinen Beitrag finden, der Ihre Frage beantwortet, posten Sie Ihre Frage zusammen mit einem Link zu einer Webseite, auf der das Problem dargestellt wird.

Lokalisierung

Wenn Sie erwarten, dass Ihr Diagramm von Menschen in verschiedenen Ländern verwendet wird, sollten Sie Ihr Diagramm möglicherweise für verschiedene Sprachen und Kulturen lokalisieren. Die einfachste Lokalisierung besteht darin, die Standardtextstrings in der UI entsprechend den Browsereinstellungen des Nutzers zu übersetzen. Eine fortgeschrittenere Form der Lokalisierung besteht darin, das Zahlenformat je nach Lokalisierung oder möglicherweise sogar vom UI-Design zu ändern. Wenn Sie Ihr Diagramm lokalisieren möchten, geben Sie in Ihrer Dokumentation die vom Diagramm unterstützten Sprachen an und geben Sie eine Standardeinstellung für eine häufig verwendete Sprache an. Es ist auch hilfreich, die Schaltfläche „Sprache ändern“ in die UI des Diagramms einzubinden, falls die Sprache falsch ist. In der Regel wird die Browsersprache anhand des HTML-Headers Accept-Language erkannt.