Widgets

Widgets

Die hockeydata Widgets bieten dir die Möglichkeit verschiedenste Sportstatistiken auf deiner Website unkompliziert einzubinden. So kannst du zum Beispiel die aktuelle Tabelle deiner Liga in kompakter Form in einer Seitenleiste platzieren und die vollständige Tabelle auf einer eigenen Seite darstellen. Mit den vielen Konfigurationsmöglichkeiten kannst du die Widgets an Funktionalität und Aussehen anpassen - so lässt sich zum Beispiel die Tabelle in deinen Vereinsfarben anzeigen oder im Spielplan dein Team farblich hervorheben.

Was sind Widgets?

Widgets sind eigenständige Bausteine, die in einem vorgegeben Container Inhalte anzeigen und an beliebigen Stellen einer Website platziert werden können. Je nach Widget-Typ gibt es verschiedene Einstellungsmöglichkeiten um die dargestellten Inhalte auswählen und das Verhalten der Widgets steuern zu können. Mit Hilfe von CSS lässt sich das Aussehen der Widgets einfach an die eigenen Bedürfnisse anpassen, sodass das Design der Website nicht gestört wird.

API Schlüssel

Um die Widgets nutzen zu können ist ein API Schlüssel erforderlich. Dieser ist an eine bestimmte Domain gebunden und kann gratis angefordert werden.

Wenn du das WordPress Plugin nutzt, kannst du in den Einstellungen deinen API Schlüssel eintragen. Dieser wird dann automatisch für jedes Widget, dass du auf deiner Seite per Shortcode oder WordPress Widget einbindest, verwendet.

Auf die Plätze, fertig, Widget!

Ein Beispiel sagt mehr als tausend Worte. Folgende Zeilen genügen um eine vollständige Tabelle einzubinden:

Beispiel 1

<script src="https://api.hockeydata.net/js/?los_standings&los_configuration_americanfootball"></script>
<link href="https://api.hockeydata.net/css/?los_standings" rel="stylesheet">
<div data-hd-widget="hockeydata.los.Standings" data-hd-widget-options='{
  "apiKey": "YOUR_API_KEY",
  "divisionId": 5,
  "sport": "americanfootball"
}'></div>

Mit dem <script> wird die hockeydata JavaScript Library geladen. Diese kümmert sich um das Laden und Anzeigen der Daten.

Die eingebundene CSS-Datei stellt die Basis für das Styling zur Verfügung. Mit eigenen CSS-Definitionen kann das Widget an die eigene Website angepasst werden.

Der <div> dient als Platzhalter für das Widget und definiert, welches Widget angezeigt werden soll sowie dessen Einstellungen als JSON.

jQuery

Die hockeydata JavaScript Library benötigt jQuery. jQuery ist eine freie JavaScript-Bibliothek und wird in vielen Content Management und Blog Systemen wie WordPress bereits mitgeliefert.

jQuery muss vor der hockeydata Library geladen werden. Verwendet deine Website jQuery noch nicht, kannst du die Bibliothek entweder herunterladen oder eines der vielen CDNs (Content Delivery Network) verwenden. Anleitungen für beide Methoden findest du auf jquery.com/download.

hockeydata JavaScript Library

Die hockeydata JavaScript Library enthält alle notwendigen Klassen, Methoden und Attribute, die für die Widgets benötigt werden und wird über ein <script> geladen. Die Basis der URL lautet https://api.hockeydata.net/js/. Dies lädt die Grundbibliothek, die durch Laden zusätzlicher Klassen an Funktionalität erweitert wird. Zusätzliche Klassen können beim Aufruf der URL über Parameter geladen werden. Der zu verwendende Parameter ist beim jeweiligen Widget definiert und auf dessen API-Beschreibungsseite zu finden.

In Beispiel 1 wären dies los_standings für die Tabelle und los_configuration_americanfootball für die standard Spalten-Konfiguration von American Football. Die vollständige URL lautet daher https://api.hockeydata.net/js/?los_standings&los_configuration_americanfootball.

Abhängige Klassen werden automatisch dazugeladen, sodass nicht jede einzeln angegeben werden muss.

Konfiguration
Da bei jeder Sportart und teilweise auch bei verschiedenen Ligen der gleichen Sportart unterschiedliche Spalten und Werte angezeigt werden, muss die entsprechende Konfiguration geladen werden. In Beispiel 1 wird die Konfiguration für American Football (los_configuration_americanfootball) geladen.

Mehrere Widgets auf einer Seite
Natürlich können mehrere Widgets auf einer Seite verwendet werden, zum Beispiel Tabelle und Spielplan untereinander in einer Seitenleiste. Um Code nicht doppelt laden zu müssen und die Anzahl der Requests zu minimieren können alle notwendigen Klassen mit einem Aufruf geladen werden, indem mehrere Parameter übergeben werden. Für Tabelle und Spielplan würde der Script-Aufruf daher so aussehen:

<script src="https://api.hockeydata.net/js/?los_schedule&los_standings&los_configuration_americanfootball"></script>

Außerdem ist es möglich, alle Widgets inklusive Konfiguration einer Sportart über folgende URL's zu laden:

American Football: https://api.hockeydata.net/js/?los_americanfootball
Eishockey: https://api.hockeydata.net/js/?los_icehockey

Performance
Da der Aufbau der Widgets erst nach dem vollständigen Laden der Website erfolgt, kann das Script zum Laden der hockeydata JavaScript Library auch am Ende der Seite eingebunden werden. Dies verhindert, dass eine Verzögerung des Ladevorgangs der Library den Aufbau der gesamten Website blockiert.

Styling

Mittels CSS kann das Design aller hockeydata Widgets an die eigenen Bedürfnisse angepasst werden. Empfohlen wird die hockeydata CSS-Basisdefinitionen zu laden und diese mit eigenen Definitionen zu überschreiben oder zu erweitern. Wie auch bei der hockeydata JavaScript Library gibt es eine URL-Basis https://api.hockeydata.net/css/, die per Parameter erweitert werden kann um weitere Definitionen für die verschiedenen Widgets zu laden. Die Einbindung des CSS erfolgt über einen <link>.

Der zu verwendende Parameter ist beim jeweiligen Widget definiert und auf dessen API-Beschreibungsseite zu finden. Hier ist kein sportartspezifischer Parameter erforderlich.

In Beispiel 1 wird das CSS für die Tabelle mit folgendem Code geladen:

<link href="https://api.hockeydata.net/css/?los_standings" rel="stylesheet">

Zusätzlich zu den Basisdefinitionen stehen verschiedene Templates zur Verfügung. Diese können ebenfalls per Parameter über die gleiche URL geladen und selbstverständlich auch weiter angepasst werden. Der Vorteil des Templates: es gibt bereits einen Stil vor, zum Beispiel Hintergrund- und Schriftfarben. Dadurch müssen nicht alle Styles von Grund auf neu definiert sondern nur noch angepasst werden. Mehr Informationen dazu gibt es auf der Seite Styling.

Grundsätzlich verwendet das Widget die bereits bestehenden Styles, also Schriftart, -farbe und -größe, Hintergrundfarbe, Zeilenhöhe, etc. und passt sich daher der Website an. Das Laden des hockeydata CSS ist daher nicht zwingend erforderlich, erleichtert aber die Anpassung des Widgets. Wichtig ist dabei die Reihenfolge der CSS-Definitionen zu beachten:

  1. Website CSS
  2. hockeydata CSS
  3. Widget CSS-Anpassungen

Ob das Website CSS und die Widget CSS-Anpassungen per <link> aus einer externen Datei eingebunden oder inline per <style> definiert werden, spielt dabei keine Rolle - wichtig ist die Reihenfolge und Spezifität.

Wie die hockeydata JavaScript Library kann das CSS auch am Ende der Seite geladen werden. Es empfiehlt sich jedoch die CSS-Definitionen zu gruppieren. So könnte es zum Beispiel aussehen:

<!-- Website CSS -->
<link href="style.css" rel="stylesheet">
 
<!-- hockeydata CSS -->
<link href="https://api.hockeydata.net/css/?los_standings" rel="stylesheet">
 
<!-- Widget CSS-Anpassungen -->
<style>
  .-hd-los-standings {
    border: 1px solid #000;
  }
</style>

HTML Markup oder JavaScript?

Es gibt grundsätzlich zwei Möglichkeiten Widgets einzubinden: entweder als HTML Markup oder mittels JavaScript mit Hilfe der JavaScript API. Das HTML Markup ist einfach zu verwenden und erfordert wenig Code, ist aber bei den Optionen beschränkt. JavaScript bietet weitaus mehr Optionen und kann Widgets in ihrer Funktionalität sogar erweitern, benötigt dafür aber etwas mehr Code. Das folgende Beispiel erzielt das gleiche Ergebnis wie Beispiel 1.

Beispiel 2

<script src="https://api.hockeydata.net/js/?los_standings&los_configuration_americanfootball"></script>
<link href="https://api.hockeydata.net/css/?los_standings" rel="stylesheet">
<div id="standings"></div>
<script>
  var standings = new hockeydata.util.Widget({
    "$domNode": jQuery("#standings"),
    "widgetName": "hockeydata.los.Standings",
    "apiKey": "YOUR_API_KEY",
    "divisionId": 5,
    "sport": "americanfootball"
  });
</script>

HTML Markup
Beim HTML Markup genügt es einen Platzhalter zu definieren und direkt in diesem die Optionen für das Widget festzulegen. Der Platzhalter benötigt dabei die beiden Attribute data-hd-widget und data-hd-widget-options.

Das Attribut data-hd-widget gibt den Namen des zu verwendenden Widgets an, dabei muss der vollständige Klassenname angegeben werden (dieser ist auf der API-Beschreibungsseite des jeweiligen Widgets zu finden). In Beispiel 1 ist dies für die Tabelle hockeydata.los.Standings.

Das zweite Attribut - data-hd-widget-options - enthält notwendige Optionen für das Widget im Format eines JSON-Objekts. Welche Optionen erforderlich sind beziehungsweise gesetzt werden können ist ebenfalls auf der API-Beschreibungsseite des jeweiligen Widgets zu finden.

JavaScript
Im Unterschied zum HTML Markup entsteht das Widget mittels JavaScript Code durch Verwendung der JavaScript API. Dabei wird eine neue Widget-Instanz erstellt und als einziger Parameter die Optionen für das Widget als JSON übergeben. Diese Optionen entsprechen dem Attribut data-hd-widget-options beim HTML Markup, müssen aber zusätzlich die Properties $domNode als jQuery Object um den Platzhalter zu definieren und widgetName mit dem vollständigen Klassennamen des Widgets enthalten.

Widget konfigurieren

Bei jedem Widget muss definiert werden um welche Sportart und Division es sich handelt. Diese und weitere Einstellungen werden in den Optionen festgelegt und machen das Widget erst funktional. Jedes Widget hat unterschiedliche Optionen, wobei nicht alle davon angegeben werden müssen. Folgende Optionen müssen bei allen Widgets auf jeden Fall gesetzt werden:

Die Parameter divisionId und sport können mit dem Division Finder ermittelt werden.

Die Optionen werden im JSON Format als Objekt angegeben:

{
  "apiKey": "YOUR_API_KEY",
  "divisionId": 5,
  "sport": "americanfootball"
}

Mein Widget wird nicht angezeigt - was tun?

Sollte dein Widget nicht oder nicht so wie du es dir vorstellst angezeigt werden, überprüfe bitte ob

  • du den richtigen Widget-Klassennamen angegeben hast
  • du ein gültiges JSON bei den Widget-Optionen und auch die korrekten Optionen für das Widget verwendest
  • der Platzhalter sichtbar ist

Hilft dir auch keine dieser Problemlösungen weiter, kannst du folgendes probieren:

  • Beachte die Groß-/Kleinschreibung sowohl beim Widget-Namen als auch bei den Optionen.
  • Überprüfe mit einem Web Inspector (in den meisten modernen Browsern integriert), ob es zu JavaScript Fehlern in der Console kommt, Daten geladen werden und sich das Widget innerhalb des Platzhalters aufbaut.

Lässt sich das Widget dennoch nicht anzeigen, kannst du gerne mit uns Kontakt aufnehmen.