Daten und Berichte

Die Datentabelle, die Kennzahl, das Diagramm, der Kalender und die Karte werden alle auf dieselbe Weise gespeist: von einem gespeicherten Bericht. Nicht von einer Entität, nicht von einem Filter, den Sie an der Komponente einstellen, und nicht von etwas, das der Browser anfragt.

Das ist Absicht. Ein Bericht zählt, summiert, verknüpft, filtert und formatiert bereits, und er ist etwas, das Sie einzeln öffnen, ausführen und prüfen können. Ein zweiter, schwächerer Abfrage-Editor in jeder Komponente wäre nur eine weitere Stelle, an der man falsch liegen kann.

Der vollständige Leitfaden zu Berichten selbst ist Berichte.

Die Regel: der Bericht grenzt sich auf den Kunden ein

Das Portal fügt dem SQL Ihres Berichts nichts hinzu. Grenzt der Bericht sich nicht auf den angemeldeten Kunden ein, sieht jeder Kunde jede Zeile.

Der angemeldete Kunde steht dem Bericht als entity zur Verfügung, die Bedingung kommt also dorthin, wo jede andere Bedingung auch hinkommt:

SELECT number, issued_on, total, status
FROM   invoices
WHERE  contact_id = {{ entity.id }}
ORDER  BY issued_on DESC

Sie haben	Sie schreiben
eine Spalte mit der ID des Kunden	WHERE contact_id = {{ entity.id }}
eine Verknüpfung, um ihn zu erreichen	verknüpfen, dann gegen {{ entity.id }} vergleichen
ein Firmenportal, Zeilen an eine Firma gebunden	WHERE account_id = {{ entity.id }}
irgendetwas am Datensatz selbst	{{ entity.email }}, {{ entity.company }}, jedes Feld

Nichts sonst im Produkt weist Sie darauf hin. Ein Bericht ohne eine solche Bedingung läuft einwandfrei, liefert Zeilen und zeichnet eine gesund aussehende Tabelle voller fremder Daten. Prüfen Sie jeden Bericht, bevor Sie ihn auf ein Portal stellen, und prüfen Sie ihn erneut, nachdem jemand ihn bearbeitet hat.

Die sicherste Gewohnheit ist, die Bedingung zuerst zu schreiben, vor den Spalten, und den Bericht als Testkunde zu öffnen, sobald die Komponente auf der Seite ist.

Datentabellen-Berichte, keine HTML-Berichte

Berichte gibt es in zwei Ausgabeformaten, und Portal-Komponenten wollen das erste:

Berichtsformat	Auf einem Portal
Datentabelle	die Tabelle, die Kennzahl, das Diagramm, der Kalender und die Karte: alle fünf
HTML	diesen Komponenten gar nicht erst angeboten

Ein HTML-Bericht rendert sein eigenes Markup und liefert keine Spalten, ein Diagramm, das auf einen zeigt, könnte also immer nur ein leeres Bild zeichnen. Genau deshalb bieten die Auswahlfelder nur Datentabellen-Berichte an. Wenn Sie die Freiheit eines HTML-Berichts auf einem Portal wollen, ist dafür die HTML-Komponente da, und sie kann es besser: sie wird dort bearbeitet, wo Sie gerade stehen, statt in einem anderen Bildschirm.

Die Spalten wählen

Sobald eine Komponente einen Bericht nennt, bietet jedes Spaltenauswahlfeld an ihr die Spalten dieses Berichts an. Es gibt keine Namenskonvention zu befolgen und nichts umzubenennen: eine Karte braucht keine Spalten namens lat und lng, sie braucht von Ihnen die Angabe, welche Spalten des Berichts das sind.

Zwei Folgen:

• Beantworten Sie zuerst die Bericht-Einstellung. Die Spaltenauswahl hat nichts anzubieten, bevor sie weiß, welchen Bericht sie lesen soll.
• Eine Spalte im Bericht umzubenennen kann eine Einstellung leeren, die auf sie zeigte. Zeichnet eine Komponente nicht mehr, nachdem jemand einen Bericht bearbeitet hat, ist das das Erste, was Sie prüfen sollten.

Was der Browser eines Kunden anfragen darf

Komponenten sind interaktiv: eine Tabelle blättert und sortiert, ein Kalender wechselt den Monat, und Ihr eigenes Markup kann eine Komponente mit anderen Parametern aktualisieren. Es lohnt sich also festzuhalten, was ein Browser beeinflussen kann und was nicht:

Komponente	Darf anpassen
Datentabelle	Zeilen pro Seite, welche Seite, Sortierspalte, Sortierrichtung
Diagramm	das Zeilenlimit
Karte	das Markierungslimit
Kalender	das Zeilenlimit und den sichtbaren Zeitraum
Alles andere	nichts

Jedes davon grenzt die Antwort ein, blättert darin oder sortiert sie um. Keines kann erweitern, was der Bericht geliefert hat, und die Limits sind auf dem Server gedeckelt, niemand kann also aus einer geblätterten Tabelle einen Vollexport machen, indem er eine ausreichend große Seite anfragt.

Die Obergrenzen

Obergrenze	Limit
Zeilen pro Anfrage	200
Gezeichnete Diagrammzeilen	500
Kalendertermine	500
Kartenmarkierungen	200

Das sind Schutzgrenzen, keine Einstellungen: irgendetwas muss zwischen einem Bericht mit hunderttausend Zeilen und einer Seite stehen, die versucht, sie zu zeichnen. Eine Komponente, die regelmäßig an eine davon stößt, ist ein Zeichen dafür, dass der Bericht enger sein sollte, meist über das Datum.

Für einen Kalender ist die Antwort der sichtbare Zeitraum:

WHERE appointment_date BETWEEN '{{ range.from }}' AND '{{ range.to }}'

So geschrieben, liefert der Bericht den Monat, den der Kunde gerade ansieht, und antwortet erneut, sobald er weiterblättert.

Für interne Nutzer geschriebene Berichte, auf einem Portal wiederverwendet

Die meisten Berichte entstehen auf einem Dashboard oder einem internen Bildschirm. Drei Dinge, die Sie prüfen sollten, bevor einer auf ein Portal kommt:

1. Die Kundenbedingung. Die Regel von oben. Ein interner Bericht hat fast nie eine, weil interne Nutzer alles sehen sollen.
2. Die Links. Spaltenformatierung baut oft Links auf interne Bildschirme, die einen Kunden zur Anmeldeseite führen. Das Markup rendert korrekt, und das Ziel ist trotzdem falsch.
3. Die Spalten. Interne IDs, Namen von Zuständigen, Margen und Einkaufspreise sind in einem internen Bericht völlig normal, und nichts davon gehört vor einen Kunden.

Eine Kopie des Berichts, für das Portal geschrieben, ist meist sauberer als der Versuch, einen Bericht beiden Zielgruppen dienen zu lassen.

So prüfen, wie ein Kunde es sähe

Die Vorschauen im Builder führen Ihre Berichte ohne Kunden im Kontext aus, was die ehrliche Vorschau ist statt einer erfundenen: ein Bericht, der gegen {{ entity.id }} geschrieben ist, erscheint in der Vorschau leer. Das ist kein Fehler, und eine Komponente, die in der Vorschau leer ist, kann völlig korrekt sein.

Um das Echte zu sehen, öffnen Sie mit Vorschau das veröffentlichte Portal und melden sich als Testkunde an: ein Datensatz auf der Kundenentität, mit einer Adresse, unter der Sie Mail empfangen können, aktiv geschaltet.