Tworzenie typów wykresów

Na tej stronie dowiesz się, jak utworzyć własny typ wykresu i udostępnić go użytkownikom.

Odbiorcy

Zakładamy, że znasz już stronę Korzystanie z wykresów. Zakładamy też, że znasz język JavaScript i programowanie zorientowane na obiekty. W internecie dostępnych jest wiele samouczków JavaScriptu.

Tworzenie wykresu

Wykresy są widoczne dla użytkownika przez utworzoną przez Ciebie bibliotekę JavaScript. Aby utworzyć bibliotekę wykresów:

1. Wybierz przestrzeń nazw dla kodu. Twój kod będzie hostowany na innych stronach, warto więc unikać konfliktów z nazwami.
2. Zaimplementuj obiekt wykresu. Zaimplementuj obiekt JavaScript, który ujawnia:
   • konstruktorem,
   • metody draw() do rysowania obiektu wewnątrz elementu DOM przekazywanego do konstruktora,
   • Wszelkie inne opcjonalne metody standardowe, których może używać klient, na przykład getSelection(),
   • Wszelkie niestandardowe metody, które chcesz udostępnić klientom.
3. [Opcjonalnie] Zaimplementuj wszystkie zdarzenia , które mają być uruchamiane przez klienta.
4. Utwórz dokumentację wykresu. Jeśli nie udokumentujesz go, użytkownicy prawdopodobnie nie będą mogli go umieścić.
5. Opublikuj wykres w galerii wykresów.

Wybierz przestrzeń nazw

Wykres możesz umieścić na stronie, na której znajdują się inne wykresy lub inny niepowiązany kod JavaScript. Aby uniknąć konfliktów z nazwami innych kodów lub klas CSS, wybierz dla kodu wykresu unikalną przestrzeń nazw. Dobrym wyborem dla przestrzeni nazw jest adres URL, którego będziesz używać do hostowania skryptu (bez WWW i wszystkich rozszerzeń). Jeśli więc wykres ma być opublikowany na stronie www.example.com, nazwa example powinna być Twoją unikalną przestrzenią nazw. Możesz dodać kolejne sufiksy rozdzielone znakiem . znaczników, by jeszcze bardziej pogrupować wykres (wszystkie wykresy Google mają przestrzeń nazw google.visualization). Użyj obiektu przestrzeni nazw do przechowywania obiektu wykresu oraz wszelkich potrzebnych zmiennych globalnych.

Oto przykład tworzenia obiektu przestrzeni nazw do przechowywania klasy wykresu o nazwie MyTable, a także wszelkich potrzebnych zmiennych globalnych:

// 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) {
  // ...
}

Unikanie konfliktów CSS

Jeśli korzystasz z CSS, pamiętaj, aby nie pisać reguł CSS, które mogą mieć wpływ na inne wykresy na stronie. Na przykład zdecydowanie odradzamy stosowanie reguły takiej jak td {color: blue;}, ponieważ wpływa ona na wszystkie pozostałe elementy <td> na stronie, nie tylko na wykresie. Jednym ze sposobów rozwiązania tego problemu jest umieszczenie całego wykresu w polu <div> nazwą klasy, a wszystkie reguły CSS mają zastosowanie tylko do elementów, które są elementami potomnymi elementu o tej nazwie klasy. Na przykład ta reguła CSS wpłynie tylko na elementy <td>, które mają element o nazwie klasy „example” jako elementem nadrzędnym.

td.example {color: blue;}

Następnie możesz owinąć wykres w <div> za pomocą :

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

Implementowanie wykresu

Musisz zaimplementować wykres jako obiekt JavaScriptu, który udostępnia standardowe metody opisane w sekcji z dokumentacją. Dwie wymagane metody to konstruktor i metody Draw(). Możesz też udostępnić użytkownikom wszelkie dodatkowe metody, które sprawdzą się w Twoim wykresie. Pamiętaj tylko, że łatwiejszy w użyciu jest lepszy.

Konstruktor

Wykres powinien ujawniać pojedynczy konstruktor, który przyjmuje pojedynczy parametr – element DOM, do którego będzie rysowany wykres. Zwykle wykresy przechowują lokalną kopię tego elementu w konstruktorze do późniejszego użycia:

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

Metoda draw()

Klasa wykresu powinna mieć zdefiniowaną metodę draw() w prototypie klasy wykresu. Metoda draw() akceptuje 2 parametry:

1. DataTable zawierający dane do wyświetlenia.
2. Opcjonalna mapa opcji nazw i wartości na wykresie. Nazwy i typy wartości opcji są określane dla Ciebie na potrzeby konkretnego wykresu. Na przykład w poniższym przykładzie wykresu powitalnego wykres obsługuje opcję o nazwie „showLineNumber” z wartością typu Boolean. Musisz obsługiwać wartość domyślną każdej opcji na wypadek, gdyby użytkownik nie przekazywał wartości dla konkretnej opcji. Ten parametr jest opcjonalny. Jeśli użytkownik nie przekaże go, musisz też przygotować się na użycie wszystkich wartości domyślnych (więcej informacji).

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

Cześć, Chart!

Oto prosty wykres, który przedstawia dane DataTable w postaci tabeli HTML:

A oto kod implementacji:

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

Umieszczanie wykresu na stronie internetowej

Aby skorzystać z poprzedniego wykresu, zapisz go w pliku .js dostępnym w przeglądarce. Następnie zapisz ten kod, zmieniając parametr źródłowy <script> tak, by wskazywał plik 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>

 

Implementowanie zdarzeń

Jeśli chcesz, by na wykresie były wywoływane przydatne zdarzenia (np. zdarzenia licznika lub zdarzenia inicjowane przez użytkownika, takie jak kliknięcia), musisz wywołać funkcję google.visualization.events.trigger z informacjami o zdarzeniu (nazwą, właściwościami do wysłania itp.). Szczegółowe informacje znajdziesz na stronie Zdarzenia. Możesz udostępnić szczegóły zdarzenia klientowi, dodając właściwości do obiektu zdarzenia, lub udostępnić na wykresie metodę get...() jakiegoś typu, a klient może ją wywołać, aby uzyskać szczegóły zdarzenia. W obu przypadkach dobrze udokumentuj swoje metody lub właściwości zdarzeń.

Dokumentowanie wykresu

Jeśli nie udokumentujesz prawidłowo wykresu, prawdopodobnie nie będziesz mieć wielu użytkowników. Pamiętaj, aby udokumentować:

• Opisz wszystkie stosowane metody. Metoda draw() jest wspólna dla wszystkich wykresów, ale każdy wykres może obsługiwać własne dodatkowe metody. Prawdopodobnie nie musisz dokumentować swojego konstruktora, chyba że działa on w sposób niestandardowy. Listę oczekiwanych metod znajdziesz na stronie referencyjnej.
• Opisz wszystkie opcje obsługiwane przez Twoją metodę draw(). Obejmują one nazwę każdej opcji, oczekiwany typ wartości i jej wartość domyślną.
• Opisz wszystkie wywoływane zdarzenia. Oznacza to nazwę i właściwości każdego zdarzenia oraz czas jego wywołania.
• Podaj adres URL biblioteki wykresów, który powinien być używany w instrukcji <script> klienta, oraz adres URL dokumentacji.
• Nadaj wykresowi pełną nazwę.
• Utwórz przykładowe strony, które pokazują, jak korzystać z wykresu z obsługiwanymi opcjami, zdarzeniami i metodami niestandardowymi.
• Jasno opisz zasady dotyczące danych na wykresie. Większość wykresów przetwarza dane w przeglądarce, ale niektóre mogą wysyłać dane na serwer, na przykład w celu utworzenia obrazu wykresu lub mapy. Jeśli wysyłasz dane na serwer:
  • Wyraźnie określ, jakie dane mają być wysyłane.
  • Zwróć uwagę, jak długo dane będą przechowywane na serwerze.
  • Dokumentuj, które encje będą miały dostęp do danych. Na przykład: firma XYZ itp.
  • Określ, czy dane mają być rejestrowane i jak długo.

Dokumentacja będzie przechowywana w tym samym miejscu co kod wykresu (patrz poniżej Przesyłanie wykresu do galerii).

Przesyłanie wykresu do galerii

Po napisaniu wykresu prześlij go do opublikowania w sekcji „Dodatkowe wykresy” naszej galerii. Przesłanie wykresu oznacza, że musisz podpisać z nami umowę, w której zobowiązujesz się, że nie będziesz tworzyć złośliwego oprogramowania ani niewłaściwie wykorzystywać danych użytkownika. Galeria to tylko lista wskaźników do utworzonych przez nas lub przez nas sprawdzonych wykresów. Możesz hostować w swojej witrynie rzeczywistą bibliotekę i dokumentację JavaScript lub pozwolić Google przechowywać na serwerze Google bibliotekę i dokumentację. Przy publikowaniu do galerii określ, czy mamy przechowywać wykres.

Rozwiązywanie problemów

Jeśli Twój kod wydaje się nie działać, oto kilka metod, które mogą pomóc Ci rozwiązać problemy:

• Sprawdź, czy nie ma literówek. Pamiętaj, że w języku JavaScript wielkość liter ma znaczenie.
• Użyj debugera JavaScriptu. W Firefoksie możesz użyć konsoli JavaScript, Venkman Debugger lub dodatku Firebug. W przeglądarce IE możesz używać narzędzia Microsoft Script Debugger.
• Przeszukaj grupę dyskusyjną interfejsu Google Chart API. Jeśli nie możesz znaleźć posta z odpowiedzią na Twoje pytanie, opublikuj je w grupie razem z linkiem do strony internetowej ilustrującej problem.

Lokalizacja

Jeśli spodziewasz się, że z Twojego wykresu będą korzystać osoby w różnych krajach, możesz go dostosować do różnych języków i kultur. Podstawowa lokalizacja to tłumaczenie standardowych ciągów tekstowych wyświetlanych w interfejsie zgodnie z ustawieniami przeglądarki użytkownika. Bardziej zaawansowaną formą lokalizacji jest zmiana formatów liczb w zależności od lokalizacji, a czasem nawet od projektu interfejsu. Jeśli zdecydujesz się przetłumaczyć wykres, wymień w dokumentacji języki obsługiwane na wykresie i podaj ustawienie domyślne często używanych języków. Warto też dodać w interfejsie wykresu przycisk „Zmień język” na wypadek, gdyby język był nieprawidłowy. Częstym sposobem wykrywania języka przeglądarki jest sprawdzenie nagłówka HTML Accept-Language.