Eines der neuen Features im neuen Application Express Release 5.1 sind die neuen Charts auf Basis von Oracle JET. JET steht für Javascript Extension Toolkit und ist eine Bibliotheks- und Utility-Sammlung für Javascript-Entwickler. Diese finden in Oracle JET alles, was sie brauchen, um damit reine Javascript-Anwendungen zu erstellen - dies ist oft sogenannte One Page Anwendungen, bei denen nur zu Beginn eine Webseite geladen wird; der ganze Rest der Anwendungsfunktionalität wird mit Javascript abgedeckt. Das Oracle JET Cookbook zeigt anhand vieler Beispiel auf, wie man Oracle JET mit Javascript verwendet.

Oracle JET - Homepage

Oracle JET enthält auch eine Reihe von Komponenten zur Visualisierung von Daten - und genau diese wurden als Grundlage für die neuen Application Express Diagramme verwendet. Nicht alle in Oracle JET verfügbaren Visualisierungen stehen als Application Express Charts bereit - zumindest noch nicht.

Oracle JET - Data Visualizations

JET-Diagramme in Application Express

Application Express enthält die komplette JET-Distribution 2.0.2 - allerdings liegen nur die Diagramme auch als deklarativ verwendbare Komponenten vor. Andere JET-Funktionen kann man als APEX-Entwickler ebenfalls verwenden; hier muss aber Javascript programmiert werden. Wegen der Abhängigkeiten von sowohl Oracle JET als auch von Application Express zur jQuery-Bibliothek kann Oracle JET in Application Express 5.1 nicht manuell durch eine neuere Version ersetzt werden.

Erstellt man in einer Application Express 5.1 Anwendung ein neues Diagramm, so bemerkt man von JET zunächst nicht viel: Allein die verfügbaren Diagrammtypen lassen erahnen, dass sich hier etwas verändert hat.

Diagrammtypen in Application Express 5.1

Gantt- und Map-Diagramme verwenden Oracle JET in der Version 5.1 noch nicht; dieser Diagrammtyp wird, wie in früheren Versionen, von der AnyChart-Engine getrieben.

Das Erstellen eines Diagramms funktioniert mehr oder weniger genauso wie in früheren APEX-Versionen. Ein Diagramm wird nach wie vor von einer SQL-Abfrage als Datenquelle getrieben und mit dem Page Designer konfiguriert. Anders als in früheren APEX-Versionen muss die SQL-Abfrage keine besondere Syntax verwenden - jede beliebige Abfrage (auch select * from emp) ist möglich.

In den Diagrammattributen wird festgelegt, welche der Ergebnisspalten als Diagrammwert, als Label oder als Link verwender werden soll. Die verschiedenen Diagrammattribute, die man als Entwickler konfiguriert, haben sich im Vergleich zu früheren Application Express-Versionen stark verändert - der Grund ist einfach, dass Oracle JET sich technisch sehr stark von dem früher verwendeten AnyChart unterscheidet.

Alle Application Express-Diagrammtypen sind aus dem Stand responsive und barrierefrei; passen sich also der Bildschirmgröße an, lassen sich auch ohne Maus bedienen und können von Screenreadern verarbeitet werden. Darüber hinaus ist es möglich, und das ist wichtig für Dashboard oder Portalseiten, das Diagramm regelmäßig aktualisieren zu lassen.

Diagramme in Application Express 5.1 sind responsive

Die einzelnen Diagramm hier mit all ihren Möglichkeiten aufzuführen, würde den Rahmen dieses Tipps sicherlich sprengen; am besten probiert man als APEX-Entwickler alle einmal aus - mit den Daten der fast überall vorhandenen Tabellen EMP und DEPT erreicht man eine ganze Menge. Möchte man die Charts direkt in Aktion sehen, so sei die Installation der Packaged Application Sample Charts empfohlen - diese enthält nahezu alle JET-Charts (und nicht nur diese) wenigstens ein Mal.

Packaged Application "Sample Charts" - Übersicht

Packaged Application "Sample Charts" - Bubble Charts

Packaged Application "Sample Charts" - Polar Charts

Die Unterstützung für Time Axis ist nützlich, wenn das Diagramm-Label vom Typ DATE oder TIMESTAMP ist. In diesen Fällen kann das Label deklarativ als Zeitachse festgelegt werden. Labels werden daraufhin nicht nur als lesbare Datumswerte angezeigt, auch mit Lücken in den Daten (Skip Gaps) oder mit Serien, die Werte für unterschiedliche Datenpunkte zurückliefern (Mixed frequency), wird Oracle JET dann problemlos fertig.

Time Axis in Oracle JET Charts

Mixed frequency ist dabei ein sehr mächtiges Attribut: Normalerweise, wenn das Diagrammlabel vom Typ NUMBER oder VARCHAR2 ist, muss man als Entwickler sicherstellen, dass alle Serien eines Diagramms Werte für die gleichen Datenpunkte zurückliefern - bei Bedarf müssen in der Query also zusätzliche NULL Werte generiert werden. Für DATE oder TIMESTAMP erledigt Mixed frequency das automatisch: Auch wenn die verschiedenen Serien Werte für unterschiedliche Datenpunkte zurückliefern, sorgt Oracle JET dafür, dass sie korrekt in die Zeitlinie des Diagramms eingetragen werden. Stacking ist dann allerdings nicht möglich. Die Sample Charts-Anwendung zeigt das sehr schön auf der Seite Combination unter Combination Chart (Regular v Mixed Frequency Time Axis).

Time Axis in Oracle JET Charts: Mixed Frequency

Upgrade von Diagrammen aus früheren Versionen nach Application Express 5.1

In einer Anwendung, die mit einem früheren Release von Application Express erstellt wurde, befinden sich, logischerweise, keine auf JET basierenden Diagramme - wie bereits erwähnt, wurden Diagramme bis einschließlich APEX 5.0 von der AnyChart-Engine getrieben. Für Gantt- und Map-Diagramme ist das auch in der Version 5.1 noch der Fall - dieser Typ wird in einem späteren Release auf Basis von JET angeboten.

Die AnyChart-Engine ist auch in Application Express 5.1 noch enthalten - und auch hinsichtlich der Diagramme funktioniert Application Express so, wie man es gewohnt ist:

Beim Upgrade einer Application Express-Instanz ändert sich an der Funktionalität der Anwendungen nichts.

AnyChart-Diagramme in APEX 5.0 sind auch AnyChart-Diagramme in APEX 5.1 - es wird nichts automatisch nach Oracle JET migriert. Nach einem APEX-Upgrade, oder nach dem Import einer Anwendung aus einem früheren Release nach APEX 5.1, sehen die Diagramme in der Anwendung also genauso aus, wie vorher. Die Unterschiede in den folgenden Abbildungen erklären sich durch unterschiedliche Tabellendaten in der alten und neuen APEX-Instanz.

Diagramme auf Basis von AnyChart in Application Express 5.0

Diagramme auf Basis von AnyChart in Application Express 5.1

Um die neuen JET-Diagramme auch in der bestehenden Anwendung nutzen zu können, muss ein Application Upgrade gemacht werden: Navigieren Sie dazu im Application Builder zunächst zu Ihrer Anwendung, dann zu den Utilities und wählen Sie dann Upgrade Application aus.

"Upgrade Application" - in den Application Utilities

Im Bereich Application Upgrade bekommen Sie die vorhandenen Anychart-Diagramme bereits als Candidate Objects angezeigt.

Vier ältere Diagrammtypen können zu JET-Diagrammen konvertiert werden

Klicken Sie dann auf die Anzahl der Candidate Objects in der rechten Berichtsspalte (in der Abbildung "4"). Daraufhin sehen Sie die in Frage kommenden Diagrammregionen im einzelnen. Sie können diese nun einzeln an oder abwählen - ein Klick auf den Button Upgrade migriert diese zu JET-Diagrammen.

Diagrammregionen lassen sich einzeln zur Migration auswählen

Die Diagrammregionen wurden zu Oracle JET Charts migriert

Die Diagrammregionen wurden zu Oracle JET Charts migriert

Diese automatische Migration kann für alle Diagramme stattfinden, die allein deklarativ erstellt wurden - die Grenze ist dort, wo das AnyChart-Diagramm mit Custom XML verändert wurde. Die folgende Abbildung enthält zwei in Application Express 5.0 erstellte Diagramme. Der Donut-Chart auf der linken Seite wurde deklarativ angepasst - der Line-Chart wurde mit Custom XML verändert, denn für die Liniendicke und -Transparenz gab es in APEX 5.0 kein deklaratives Attribut.

Ein mit "Custom XML" verändertes AnyChart Diagramm

Unmittelbar nach dem Import in die Application Express 5.1 Umgebung sieht das Diagramm, wie schon erwähnt, genauso aus, wie in APEX 5.0. Im Bereich Application Upgrade wird nun allerdings ein Candiate Object weniger zur Migration angeboten - es fehlt genau das Diagramm, welches mit Custom XML manuell verändert wurde. Dieses Diagramm kann nicht automatisch migriert werden - der Entwickler muss selbst ran.

Mit "Custom XML" veränderte Diagramme werden nicht zur Migration angeboten

JET Diagramme mit Javascript-Code anpassen

APEX-Entwickler können neben dem Page Designer auch mit der Oracle JET Javascript API direkt arbeiten; zu deren Möglichkeiten, konsultiert man am besten die Oracle JET Dokumentation zum Objekt ojChart.

Javascript-Dokumentation zum Oracle JET Objekt "ojChart"

Im Zusammenspiel mit Application Express Dynamic Actions lässt sich die Oracle JET Javascript API sehr gut verwenden, um Diagramme mit dem Rest einer APEX-Seite zu integrieren. So könnte man die Ausrichtung eines Balkendiagramms (vertikal oder horizontal) per Klick auf einen Button ändern. Und das ist sehr einfach: Zunächst sollte man sicherstellen, dass die Diagrammregion eine Static ID hat, damit man das Diagramm von Javascript aus ansprechen kann. Dann erzeugt man einen Button und eine Dynamic Action, die bei Klick auf den Button den folgenden Javascript-Code ausführt.

// changes chart orientation to vertical
$("#{chart-region-static-id}_jet").ojChart({orientation: 'vertical'});

Auch hierfür ist ein Beispiel in der Sample Charts-Anwendung auf der Seite Area enthalten.

Diagramm-Ausrichtung per Button-Klick ändern

Ein weiteres Anwendungsgebiet für die Javascript-API ist die Konfiguration des Diagramms selbst - die Javascript-API erlaubt es hier, weit über die Möglichkeiten des Page Designer hinauszugehen. Dazu dient das Diagrammattribut Javascript Code im Bereich Advanced .

Mit dem Attribut "Javascript Code" im Bereich "Advanced" können JET-Diagramme angepasst werden

Dort wird eine Javascript-Funktion hinterlegt. Diese bekommt ein Oracle JET-Konfigurationsobjekt übergeben. Mit dem Code in der Funktion verändert man das Objekt und gibt es wieder zurück. In der Implementierung ist man als Entwickler völlig frei - man kann also den vollen Funktionsumfang der Oracle JET API nutzen.

Um die Liniendicke eines Liniendiagramms anzupassen, würde sich das Attribut styleDefaults.lineWidth - aber Vorsicht: In APEX 5.1 gibt es dafür ein deklaratives Attribut - und diese sind immer vorzuziehen. Bevor Sie also in die Javascript-Konfiguration einsteigen, schauen Sie immer nach, ob es nicht doch ein deklaratives Attribut im Page Designer gibt.

In diesem Dokument wollen wir die Javascript-Konfiguration für den Marker eines Liniendiagramms testen: Deklarativ kann man auswählen, ob der Marker angezeigt werden und welcher Marker Shape konkret verwendet werden soll - mit Javascript geht etwas mehr: Um den Marker mit Javascript zu konfigurieren, hinterlegen Sie also im Bereich Advanced - Javascript Code die folgende Javascript-Funktion.

function( o ) {
    o.styleDefaults.markerDisplayed = "on";
    o.styleDefaults.markerShape     = "human";
    o.styleDefaults.markerSize      = 15;
    o.styleDefaults.markerColor     = "red";
    return o;
}

Javascript-Konfiguration eines JET-Charts im Page Designer

Das Ergebnis sieht dann in etwa wie in der folgenden Abbildung aus.

Ergebnis: Ein per Javascript angepasster JET-Chart

Mit Javascript können Sie die volle JET Programmierschnittstelle und damit alle Funktionalität nutzen - beachten Sie aber, dass Sie dann kein deklaratives Diagramm mehr verwenden; Sie finden die Eigenschaften ihres Diagramms nicht mehr in den Tabellen des Application Express-Repository wieder - können also die Möglichkeiten der deklarativen Entwicklung nur noch eingeschränkt verwenden. Deklarative Attribute sollten einer Javascript-Konfiguration stets vorgezogen werden.

Zurück zur Community-Seite