Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
722 lines (606 sloc) 22.7 KB

image alt text

North Data Widget API

Zur Einbindung der Visualisierungen (interaktiven Grafiken) von North Data.

Inhaltsverzeichnis

Übersicht

Folgende Widgets sind aktuell verfübar:

type Beschreibung Bild Beispiel-Seite
history Firmenhistorie (Timeline) https://www.northdata.de/widgetTestHistory.html
vita Personenhistorie https://www.northdata.de/widgetTestVita.html
graph Netzwerk einer Firma oder Person` https://www.northdata.de/widgetTestGraph.html
pubTable Publikationen einer Firma oder Person https://www.northdata.de/widgetTestPubTable.html<
barChart Balkendiagramm für finanzielle Kennzahlen https://www.northdata.de/widgetTestBarChart.html
sheet Tabellarische Darstellung der Bilanz oder GuV https://www.northdata.de/widgetTestSheet.html
financials Tabelle mit finanziellen Kennzahlen https://www.northdata.de/widgetTestFinancials.html
drillDown Darstellung der Größe der wichtigsten Jahresabschlussposten als unterteiltes Rechteck https://www.northdata.de/widgetTestDrillDown.html

Künftige Widgets

Folgende Widgets werden in Kürze verfügbar sein:

Beschreibung Status
Firmen-Stammdaten Abgeschlossen, Dokumentation fehlt
Personen-Stammdaten Abgeschlossen, Dokumentation fehlt
Firmensuche Abgeschlossen, Dokumentation fehlt
Powersuche In Entwicklung
Interaktive Karte In Entwicklung

Einbindung von Widgets

Zur Einbindung werden benötigt: 1. externe Scripts, 2. externes Stylesheet, 3. Initialisierung/Konfigurationscode:

  1. Externe Scripts:
<script src="[https://d3js.org/d3.v3.min.js](https://d3js.org/d3.v3.min.js)" charset="utf-8"></script>
<script src="[https://www.northdata.de/js/viz.min.js](https://www.biz-q.com/js/viz.min.js)"></script>

D3 ist eine verbreitete Open-Source-Visualisierungsbibliothek (https://d3js.org/). Wenn D3 bereits eingebunden wurde, kann der erste Script-Tag entfallen.

  1. Externes Stylesheet:

Über die drei Parameter können Farben in der Netzwerkdarstellung ausgewählt werden: Farbe des primären Knoten (color1), Farbe der anderen Knoten (color2), Farbe der anderen Knoten bei Mouse-Hover (color3)

  1. Initialisierung und Konfiguration per Javascript
<figure id="graph" data-layout="graph" data-name="Weiler Werkzeugmaschinen GmbH" data-address="Emskirchen" data-min-height="300"></figure>
<script>
   new NorthData.Widget( document.getElementById("graph"), { /*options*/ }   )
</script>

Für jede Visualisierung muss ein Widget-Objekt angelegt werden, mit einem HTML-Element als "Root".

Konfiguration

Die Optionen können entweder als zweiter Parameter in Javascript übergeben werden, oder als Data-Attributes am HTML-Element.

Beispiel Javascript:

<script>
   new NorthData.Widget( document.getElementById("myFigure"), { 
    layout: "history",
    apiKey: "abcd-wxyz",
    name: "Weiler Werkzeugmaschinen GmbH",
    address: "Emskirchen",
    minHeight: 300,
    success: function() { console.info("ok") },
    error: function(error) { console.error(error) }
  })
</script>

Beispiel HTML-Element:

<figure id="myFigure" data-layout="graph" data-name="Weiler Werkzeugmaschinen GmbH" data-address="Emskirchen" data-min-height="300" data-api-key="abcd-wxyz"></figure>

Wichtig: HTML-Data-Attributes werden mit Bindestrichen formatiert, nicht als Camel-Case. Also minHeight in Javascript entspricht data-min-height in HTML.

Javascript-Optionen und HTML-Data-Attributen können auch frei kombiniert werden. (Die Javascript-Optionen überschreiben die Attribute.)

Bei Javascript-Optionen vom Typ Zahl oder String können auch Funktionen verwendet werden, die passende Werte zurückliefern.

Liste Widget-übergreifender Optionen

Name Typ Erklärung
apiKey String API Key (siehe Autorisierung)
type String Auswahl der grafischen Darstellung: graph: Netzwerk der Person bzw. der Firma history: Historie (Timeline) barChart: Balkendiagramm sheet: tabellarische Darstellung der Bilanz/GuV drillDown: Darstellung der Größe der wichtigsten Jahresabschlussposten als unterteiltes Rechteck pubTable: Tabelle der neuesten Publikationen dendrogram: Horizontale Baumdarstellung (auf northdata.de verwendet zur Darstellung der Publikationsgliederung)
domain String Typ des dargestellten Objekts (optional)
company: Firma (default)
person: Person
hrb: Handelsregisterbekanntmachung
name String Name des Objekts, z.B. Firmenname
address String optional, aber verbessert die Wahrscheinlichkeit eines eindeutigen Suchergebnis Bsp: Strasse Nr. 123, 12345 Stadt oder auch nur Hamburg
registerCity String Sitz des Amtsgericht, optional, aber verbessert die Wahrscheinlichkeit eines eindeutigen Suchergebnis
registerId String Handelsregister in der Form HRA 12345
minHeight Zahl minimale Höhe der Darstellung in Pixel
maxHeight Zahl maximale Höhe in Pixel
ratio Zahl fixes Verhältnis von Höhe zu Breite
success Funktion wird aufgerufen, wenn das Widget erfolgreich erstellt wurde
error Funktion wird im Fehler-Fall aufgerufen. Erhält als Argument eine Fehlermeldung oder ein Error-Objekt

Firmen-Identifikation

Die Firma wird über die Konfigurationsoptionen name, address, registerCity und registerName identifiziert.

  1. Es muss mindestens die Kombination Name/Ort oder Amtsgericht/HR angegeben werden – idealerweise beide.

  2. Verwenden Sie als Adresse einfach nur den Ort. Dies ist absolut ausreichend zur Identifikation: kleine Fehler der Adresse (Hausnummern!) können dazu führen, dass eine Firma nicht identifiziert wird.

  3. Die Identifikation der Firma ist ansonsten weitgehend tolerant gegenüber verschiedenen Schreibweisen der Firma, früheren Namen/Orten, unterschiedlichen Schreibweisen des Orts, alten Formen des HR-Zeichen, etc.

Autorisierung

Die Autorisierung erfolgt per API-Key (wie beim Daten-API), oder über die Freischaltung der Domain, wo die Widgets eingebunden werden. Um einen API-Key zu erhalten bzw. eine Domain freischalten zu lassen, wenden Sie sich bitte an North Data.

Der API-Key sollte nur beim Testen verwendet werden. Beim Testen ist der API Key meistens erforderlich, da die beim Testen verwendete Domain nicht freigeschaltet ist.

Im Produktionsbetrieb sollte der API-Key nicht verwendet werden, da er im HTML-Source-Code sichtbar ist.

Abmessungen

Widgets nutzen immer die vorgegebene Breite des HTML-Elements. Die Höhe passen sie aber zur optimalen Darstellung dynamisch an.

Navigation / Click Handler

Interaktivität und User Engagement der Netzwerk- und Historiendarstellung werden maßgeblich verbessert, wenn die Knoten anklickbar sind und weitere Seiten verlinken. Dazu können Click Event Handler über die Optionen companyClick, personClick und publicationClick definiert werden:

function handleCompanyClick(node) {
  var hr = node.registerCity + " " + node.registerId  
  var url = "/companies.html?hr=" + encodeURIComponent(hr)
  window.location.assign(url)
}

new NorthData.Widget( myFigure, { 
  companyClick: handleCompanyClick,
  // personClick: …,
  // publicationClick: ...
})

Die Optionen companyClick, personClick und publicationClick sollten nur gesetzt werden, wenn der Click tatsächlich behandlelt wird! (Grund: korrekte Darstellung des Mauszeigers.)

Die Attribute des der Funktion übergebenen Knoten (im Beispiel: node) sind in der folgenden Tabelle zusammengestellt.

Attribut Erläuterung
name Name (z.B. Name der Firma oder der Person)
text Beschriftung des Knotens (ggf. gekürzter Name)
address Adresse (Firmen, Personen - falls bekannt)
registerName Sitz des Amtsgericht (nur Firmen)
registerId Handelsregister in der Form HRA 12345 (nur Firmen)
firstName bei Personen
lastName bei Personen
birthDate bei Personen (falls bekannt)
id interne North Data ID
url bei Publikationen (in der Regel keine öffentliche URL, da die Publikationen nicht öffentlich sind. Kann aber als eindeutiger Schlüssel für eine Publikationen verwendet werden)
hash bei Publikationen (Hashwert über den Publikationstext. Kann als Schlüssel verwendet werden)

Layout von Mehrfach-Grafiken / Item Handler

Verschiedene Widgets können mehrere Grafiken zu einer Firma erzeugen: Balkendiagramme (Widget-Type barChart) für Umsatz, Gewinn, usw., die tabellarische Darstellung der Bilanz neben der Bilanz auch eine Gewinn- und Verlustrechnung.

image alt text

Es gibt in diesem Fall viele Möglichkeiten der Darstellung: nebeneinander, untereinander, oder - häufig die eleganteste Lösung - in Tabs. Die Darstellung kann angepasst werden über einen Item-Handler:

function wrapChart(title, element) {
  // wrap title and element in figure and legend tags
  var figure = document.createElement("figure")
  var legend = document.createElement("legend")
  legend.textContent = title
  figure.appendChild(legend)
  figure.appendChild(element)
  var chart = document.createElement("div")
  chart.className = "chart"
  chart.appendChild(legend)
  chart.appendChild(figure)
  return chart
}

new NorthData.Widget( myFigure, { 
  type: "barChart",
  handleItem: wrapChart
})

Dem Item-Handler werden die Überschrift der Grafik (z.B. "Gewinn") und das jeweilige Grafikelement übergeben. Der Rückgabewert ist das "neue Element", was dann in das Dokument eingefügt wird, oder null, falls nichts eingefügt wird (d.h., das komplette DOM-Handling von der Funktion übernommen wird). Beispiel siehe hier: https://www.northdata.de/widgetTestBarChart.html

Ist kein Item-Handler definiert, wird nur die Überschrift in einen <h2>-Tag gesetzt.

Widget-Referenz

Im folgenden werden die verschiedenen Widgets im Detail vorgestellt, und die nur für sie jeweils verfügbaren Konfigurations-Optionen aufgelistet.

Widget-Typ "history"

Stellt die wichtigsten Ereignisse zu einer Firma als Timeline dar. Beispielseite: https://www.northdata.de/widgetTestHistory.html

image alt text

Besondere Konfigurations-Optionen
Name Typ Erklärung
type String Auswahl der grafischen Darstellung: history
rootColor Farbe Farbe, auf deren Basis eine passende Farbpalette für die Färbung der Ereignisse erstellt wird.
maxEvents Zahl Maximale Anzahl der angezeigten Ereignisse. Default: 25
companyClick Funktion siehe Abschnitt Navigation / Click Handler
personClick Funktion siehe Abschnitt Navigation / Click Handler
publicationClick Funktion siehe Abschnitt Navigation / Click Handler

Widget-Typ "vita"

Stellt die wichtigsten Stationen einer Person in einer Timeline dar. Beispielseite: https://www.northdata.de/widgetTestVita.html

image alt text

Besondere Konfigurations-Optionen
Name Typ Erklärung
type String Auswahl der grafischen Darstellung: vita
maxLines Zahl Maximale Anzahl der angezeigten Zeilen. Default: 15
companyClick Funktion siehe Abschnitt Navigation / Click Handler

Widget-Typ "graph"

Stellt das Netzwerk einer Firma oder Person, d.h. die Verflechtungen mit Firmen (Beherrschungen, Komplementäre, etc.) und Personen (Geschäftsführer, Vorstände, etc.) als Graph dar.

Beispielseite: https://www.northdata.de/widgetTestGraph.html

image alt text

Besondere Konfigurations-Optionen
Name Typ Erklärung
type String Auswahl der grafischen Darstellung: graph
maxNodes Zahl bei Layouts "graph", "dendrogram": Maximale Anzahl der angezeigten Knoten. Default: 12
companyClick Funktion siehe Abschnitt Navigation / Click Handler
personClick Funktion siehe Abschnitt Navigation / Click Handler

Widget-Typ "pubTable"

Interaktive Liste von Publikationen (Handelsregister, Insolvenzregister) zur jeweiligen Firma.

Beispielseite: https://www.northdata.de/widgetTestPubTable.html

Die einzelnen Publikationen können durch Klick auf der Überschrift ein- und ausgeklappt werden. Semantische Konzepte wie Firmen oder Personen sind im HTML-Text markiert, und können per CSS in der Darstellung verändert werden.

image alt text

Besondere Konfigurations-Optionen

Name Typ Erklärung
type String Auswahl der grafischen Darstellung: pubTable
maxRows Zahl Maximale Anzahl der angezeigten Elemente. Default: 25

Widget-Typ "barChart"

Stellt finanzielle Kennzahlen als Balkendiagramm dar.

Beispielseite: https://www.northdata.de/widgetTestBarChart.html

image alt text

Besondere Konfigurations-Optionen

Name Typ Erklärung
type String Auswahl der grafischen Darstellung: barChart
items Array of String Gewünschte Kennzahlen: Liste der IDs. Default: ["earnings", "revenue", "tax", "employees"]. zu den möglichen IDs siehe Finanzielle Kennzahlen
handleItem Funktion siehe Abschnitt Layout von Mehrfach-Grafiken / Item Handler
colors Array von Farben 3 Farbangaben, Nr. 1 für absolute Werte (z.B. Umsatz), Nr. 2 für positive (z.B. Gewinn), Nr. 3 für negative (z.B. Verlust)
maxYears Zahl Maximale Anzahl der angezeigten Jahre. Default: 8
chronology String Zeitliche Reihenfolge: Wert "normal" für aufsteigend, Wert "reverse" für absteigend. Default: "normal"

Widget-Typ "financials"

Stellt finanzielle Kennzahlen (soweit verfügbar) als Tabelle dar.

Beispiel: https://www.northdata.de/widgetTestFinancials.html

Das Tabellen-"Basis-Styling" ist nur rudimentär, so dass Sie es problemlos nach Ihren Bedürfnissen anpassen können. Möchten Sie das nicht tun, kann ein erweitertes Styling über folgende CSS-Datei eingebunden werden:

https://www.northdata.de/css/styling.css

image alt text

Besondere Konfigurations-Optionen

Name Typ Erklärung
type String Auswahl der grafischen Darstellung: financials
maxYears Zahl Maximale Anzahl der angezeigten Jahre. Default: 2
chronology String Zeitliche Reihenfolge: Wert "normal" für aufsteigend, Wert "reverse" für absteigend. Default: "normal"
popup Funktion Beim Click auf die Quellenangabe werden Auszüge der Originalpublikation in einem Popup-Dialog gezeigt. Durch Angabe einer Funktion function(title, html) können modale Dialog der eigenen UI-Library verwendet werden.

Widget-Typ "sheets"

Stellt Bilanz und Gewinn-/Verlustrechnung (soweit verfügbar) als interaktive Tabelle dar. Summen-Zeilen können per Klick ein- und aufgeklappt werden.

Beispielseite: https://www.northdata.de/widgetTestSheet.html

Das Tabellen-"Styling" ist nur rudimentär, so dass sie es problemlos nach Ihren Bedürfnissen anpassen können. Möchten Sie das nicht tun, kann ein erweitertes Styling kann über folgende CSS-Datei eingebunden werden:

https://www.northdata.de/css/styling.css

image alt text

Besondere Konfigurations-Optionen

Name Typ Erklärung
type String Auswahl der grafischen Darstellung: financials
maxYears Zahl Maximale Anzahl der angezeigten Jahre. Default: 2
chronology String Zeitliche Reihenfolge: Wert "normal" für aufsteigend, Wert "reverse" für absteigend. Default: "normal"
items Array of String Gewünschte Tabellen als Liste von Strings. Default: ["balance", "income"]. Mögliche Angaben: balance - Bilanz income - Gewinn- und Verlustrechnung
handleItem Funktion siehe Abschnitt Layout von Mehrfach-Grafiken / Item Handler
popup Funktion Beim Click auf die Quellenangabe werden Auszüge der Originalpublikation in einem Popup-Dialog gezeigt. Durch Angabe einer Funktion function(title, html) können modale Dialog der eigenen UI-Library verwendet werden.

Widget-Typ "drillDown"

Stellt die größten Positionen in den Ausgaben, Aktiva und Passiva des neuesten verfügbaren Jahresabschluss als untergliedertes Rechteck dar. Die Fläche der jeweiligen Boxen entspricht der Größe der Position, so dass die Größenverhältnisse auf den ersten Blick ersichtlich sind. In der Bilanz zusammengehörige Position erhalten "ähnliche" Farben.

Beispielseite: https://www.northdata.de/widgetTestDrillDown.html

image alt text

Besondere Konfigurations-Optionen

Name Typ Erklärung
type String Auswahl der grafischen Darstellung: drillDown
rootColor Farbe Farbe, auf deren Basis eine passende Farbpalette erstellt wird.
items Array of String Gewünschte Grafiken als Liste von Strings. Default: ["cost", "assets", "liabilities"]. Mögliche Angaben: cost - Ausgaben assets - Aktiva liabilities - Passiva
handleItem Funktion siehe Abschnitt Layout von Mehrfach-Grafiken / Item Handler
You can’t perform that action at this time.