Modale Dialoge

APEX 5.0 ist da. Jetzt können alle neuen Funktionen auch in einer eigenen Installation verwendet werden. In diesem Community-Tipp geht es um die neuen Modalen Dialoge, die ab APEX 5.0 out-of-the-box enthalten sind und keine zusätzlichen Plugins oder Javascript-Bibliotheken mehr benötigen. Ein modaler Dialog "sperrt" den Rest der Anwendung, solange er aktiv ist: Der Endanwender muss sich mit diesem Dialog beschäftigen - ihn zu Ende führen oder abbrechen - bevor er zu einer anderen Stelle der Anwendung navigieren kann.

Modale Dialoge sind ein sehr nützliches Element der Benutzerführung. Bislang werden Seiten in APEX, aber auch in anderen Webanwendungen, einfach in einem neuen Browserfenster geöffnet. Viele Endanwender beschäftigen sich jedoch gar nicht mit dem geöffneten Dialog, sondern arbeiten erstmal auf der "Hauptseite" weiter. Der geöffnete Dialog bleibt "im Hintergrund" offen und wird nach einer Weile vergessen. Unter Umständen erst viel später fällt der noch offene Dialog auf und der Anwendung möchte diesen bearbeiten; nun ist der Kontext dieses Dialogs aber längst verlorengegangen.

Diese Situation wird durch modale Dialoge verhindert - mit dem Öffnen des Dialogs wird die Hauptseite "gesperrt" und kann nicht mehr bearbeitet werden - der Dialog muss zuerst zu Ende geführt werden. Der Endanwender wird mit modalen Dialogen etwas "restriktiver" durch die Anwendung geführt, was typischerweise zu weniger Komplexität und damit auch zu einfacheren Anwendungen und weniger Fehlern durch Endbenutzer führt.

Abbildung 1: Modale Dialoge in Aktion

Einen ersten modalen Dialog erstellen

Eine APEX-Seite als modalen Dialog einzurichten ist ganz einfach. Erstellen Sie zunächst - als Ausgangspunkt - eine neue APEX-Anwendung mit einen Bericht und einem Formular auf die (wohlbekannte und in den meisten APEX-Workspaces bereits enthaltene) Tabelle EMP (wenn Ihnen die Tabelle fehlt, finden Sie hier ein Skript). Bereits bei Auswahl der Option Report and Form können Sie festlegen, ob die Formularseite als normale Seite, als einfacher Dialog oder als modaler Dialog eingerichtet werden soll - belassen Sie die Einstellung zunächst bei Normal (Abbildung 2).

Abbildung 2: Erstellen einer neuen Seite "Report and Form" - Modal oder nicht?

Die Anwendungsseiten funktionieren so, wie man es gewohnt ist. Ein Klick auf den Bleistift führt zur Formularseite, die neu in das Browserfenster geladen wird. Viele Nutzer halten nun gleichzeitig die Taste [Strg] fest und das Formular öffnet sich in einem neuen Browserfenster oder einer Reiterkarte - und schon hat man zwei Dialoge offen.

Abbildung 3: Bericht auf die Tabelle EMP - mit "Bleistift" zum Editieren

Abbildung 4: Formular zum Editieren - als normale APEX-Seite

Die Formularseite soll nun zu einem modalen Dialog werden. Navigieren Sie dazu zum Page Designer für die Formularseite. Klicken Sie im Navigationsbaum links den Eintrag für die Seite an (Root-Knoten) und stellen Sie im Property-Editor rechts den Eintrag Page Mode von Normal auf Modal Dialog um (Abbildung 5).

Abbildung 5: Umstellen der Formularseite zu einem modalen Dialog

Der erste "Nebeneffekt", den Sie nun bemerken ist, dass sich die Seite nicht mehr aus dem Page Designer heraus starten lässt - ein modaler Dialog kann nur aus einer anderen APEX-Seite heraus gestartet werden (Abbildung 6).

Abbildung 6: APEX-Seiten, die modale Dialoge sind, können nicht "Standalone" gestartet werden"

Starten Sie also die Seite mit dem Bericht (oder machen Sie dort einen Refresh) und klicken Sie nochmals auf den Bleistift zum Editieren. Voilá: Das Formular ist nun ein modaler Dialog (Abbildung 7).

Abbildung 7: Das Formular für die Tabelle "EMP" ist nun ein modaler Dialog

Fährt man mit der Maus über den Titel des modalen Dialogs, so stellt man fest, dass er mit Drag & Drop verschoben werden kann. Die ausgegraute Hauptseite kann aber erst wieder bedient werden, wenn der modale Dialog geschlossen wurde - entweder mit einem der Buttons oder mit dem Kreuzchen oben rechts. Nachdem Sie nun die grundsätzliche Funktionsweise des modalen Dialogs kennen, schauen wir uns im folgenden an, wie sich der modale Dialog konfigurieren lässt.

Einstellungen für modale Dialoge

Der neue modale Dialog kann zwar per Drag & Drop verschoben werden, die Größe lässt sich aber nicht einstellen. Das soll nun geändert werden. Navigieren Sie im Page Designer also nochmals zur Formularseite, die nun ein modaler Dialog ist. Wählen Sie im Baum links wiederum die Seite selbst aus und suchen Sie im Property Editor rechts den Bereich Dialog aus. Dort können Sie die Eigenschaften des modalen Dialogs beeinflussen. Für die Breite, Höhe und maximale Breite (letzteres ist wichtig, wenn die Breite in Prozent angegeben wird) sind explizite Attribute vorhanden. Daneben gibt es ein Feld für Attributes; und hier können eine ganze Menge Einstellungen vorgenommen werden. Tragen Sie 80% bei Width und resizable:true bei Attributes ein und speichern Sie die Änderung ab (Abbildung 8).

Abbildung 8: Der modale Dialog soll 80% der Bildschirmbreite einnehmen und "resizable" sein

Machen Sie dann (das ist wichtig) einen Refresh auf der Seite mit dem Bericht und klicken Sie nochmals das Bleistiftsymbol an. Nun ist der modale Dialog breiter und Sie können, wenn Sie mit der Maus an dessen Ränder fahren, die Größe verändern.

Abbildung 9: Die Größe des modalen Dialogs lässt sich nun verändern

Wie schon gesagt, können Sie bei der Konfiguration des modalen Dialogs unter Attributes eine ganze Reihe an Einstellungen vornehmen. Die Dokumentation zum jQuery Element jQuery UI Dialog enthält eine Liste aller einstellbaren Eigenschaften. Im Zusammenspiel mit resizable ist es sinnvoll, Minima und Maxima für Höhe und Breite einzustellen. Tragen Sie für den nächsten Versuch also folgende Attributes ein.

resizable: true,
minHeight: 300,
maxHeight: 600,
minWidth: 500

Der Dialog sieht aus wie vorhin, die Möglichkeiten zur Änderung der Größe finden nun aber Grenzen. Besonders interessant ist die Möglichkeit, Effekte beim Darstellen des Dialogs zu aktivieren. Allein mit Eintragungen bei Attributes und ohne weiteren Aufwand können Sie einen Fade-Effekt oder einen Slide-Effekt realisieren. Tragen Sie für Fade-In und Fade-Out folgende Attributes ein.

resizable: true,
minHeight: 300,
maxHeight: 600,
minWidth: 500,
show: {effect: 'fadeIn', duration: 1000},
hide: {effect: 'fadeOut', duration: 1000}

Wenn Sie den modalen Dialog nun ausprobieren (Refresh auf der Berichtsseite nicht vergessen), bemerken Sie, dass der Dialog nun über eine Sekunde (1000 Millisekunden) hinweg ein- und ausgeblendet wird - mit den konkreten Zahlenwerten können Sie sicherlich "spielen". Ein weiterer Effekt ist Slide-Up bzw. Slide-Down. Probieren Sie es aus.

resizable: true,
minHeight: 300,
maxHeight: 600,
minWidth: 500,
show: {effect: 'slideDown', duration: 1000},
hide: {effect: 'slideUp', duration: 1000}

Es stehen sogar noch weitere Effekte bereit. Allerdings müssen Sie Ihrer APEX-Seite dazu zusätzliche Javascript-Dateien hinzufügen, da APEX diese standardmäßig zwar enthält, aber nicht lädt. Für die Effekte bounce, drop, fold und clip benötigen Sie die folgenden Javascript-Dateien.

#JQUERYUI_DIRECTORY#ui/#MIN_DIRECTORY#jquery.ui.effect-bounce#MIN#.js
#JQUERYUI_DIRECTORY#ui/#MIN_DIRECTORY#jquery.ui.effect-drop#MIN#.js
#JQUERYUI_DIRECTORY#ui/#MIN_DIRECTORY#jquery.ui.effect-fold#MIN#.js
#JQUERYUI_DIRECTORY#ui/#MIN_DIRECTORY#jquery.ui.effect-clip#MIN#.js

Binden Sie diese Javascript-Dateien nun in die APEX-Anwendung ein. Der einfachste und beste Weg, diese für alle APEX-Seiten verfügbar zu machen, ist das Hinzufügen der Dateien zum User Interface. Navigieren Sie dazu zu den Gemeinsamen Komponenten und dort zum Bereich User Interface (Abbildung 11).

Abbildung 10: Bereich User Interface in den Gemeinsamen Komponenten

Wählen Sie dann das von Ihrer Anwendung verwendete User Interface Desktop aus, indem Sie auf den Bleistift links klicken (Abbildung 11).

Abbildung 11: User Interface "Desktop" bearbeiten

Navigieren Sie dann in den Bereich Javascript und tragen Sie die vier Links in den Bereich File URLs wie folgt ein (Abbildung 12).

Abbildung 12: File URLs für Javascript Effekte eintragen

Nun werden diese vier Javascript-Dateien zu jeder APEX-Seite dazugeladen. Also können Sie vier zusätzliche Effekte für ihre modalen Dialoge nutzen: bounce, drop, clip und fold. Um, zum Beispiel, bounce als Effekt für die Darstellung und drop als Effekt zum Schließen des modalen Dialogs zu nutzen, navigieren Sie zuerst wieder im Page Designer zur APEX-Seite mit dem modalen Dialog und tragen in den Seitenattributen (Property Editor) im Bereich Dialog unter Attributes folgendes ein.

resizable: true,
minHeight: 300,
maxHeight: 600,
minWidth: 500,
show: {effect: 'bounce', duration: 1000},
hide: {effect: 'drop', duration: 1000}

Führen Sie, wie vorhin, einen Refresh auf die Berichtsseite durch und klicken Sie auf den Bleistift im Bericht, um den modalen Dialog zu öffnen. Beobachten Sie den Effekt und wählen Sie schließlich den aus, der Ihnen am besten gefällt.

Modale Dialoge und Javascript

APEX stellt Ihnen neben der deklarativen Unterstützung für modale Dialoge auch eine Javascript-Programmierschnittstelle bereit. So können Sie einen modalen Dialog auch per Javascript-Aufruf öffnen und schließen - und was noch wichtiger ist: Sie können Daten zwischen dem modalen Dialog und der "Hauptseite" austauschen - wie das geht, erfahren Sie im folgenden Beispiel.

Es soll ein modaler Dialog verwendet werden, um eine ganze APEX-Seite mit einem Bericht als Auswahlliste zu verwenden. Auf der Hauptseite befindet sich also ein Formular mit einem Formularelement. Da eine einfache Auswahlliste nicht ausreicht, möchte man einen modalen Dialog dazu verwenden - ein APEX-Bericht kann hier viele Details anzeigen. Sobald der Nutzer eine Auswahl getroffen hat, soll der Dialog geschlossen und die Auswahl an die Hauptseite zurückgegeben werden.

Als Ausgangspunkt verwenden wir das bereits vorhandene Formular, welches ja bereits ein modaler Dialog ist. Für das Eingabefeld P3_MGR soll nun mit Hilfe eines modalen Dialogs eine "Super-Auswahlliste" erstellt werden.

Abbildung 13: Eingabefeld "MGR"

Platzieren Sie einen neuen Button rechts neben dem Element P3_MGR (nennen Sie ihn bspw. CHOOSE); er soll bei Klick einen Redirect auf Seite 10 Ihrer Anwendung machen - diese Seite 10 existiert noch nicht - die legen Sie gleich im nächsten Schritt an. Wenn Sie möchten, konfigurieren Sie den Button noch ein wenig, bis er so im Formular steht, wie Sie es haben möchten.

Abbildung 14: Zusätzliche Schaltfläche zum Verzweig auf Seite 10

Das Formular (immer noch ein modaler Dialog) sieht nun wie in Abbildung 15 aus.

Abbildung 15: Das veränderte Formular

Erzeugen Sie dann die neue Seite 10 - sie soll einfach nur einen klassischen Bericht auf die Tabelle EMP enthalten. Einen solchen haben wir zwar schon mit der Startseite, für diesen zweiten modalen Dialog brauchen Sie aber eine separate Seite. Legen Sie die Seite als Seite 10 an (denn auf diese verzweigt die gerade angelegte Schaltfläche) und legen Sie den Seitentyp wiederum als Modal Dialog fest (Abbildung 16).

Abbildung 16: Neue Seite mit Bericht auf Tabelle EMP als modalen Dialog anlegen

Nehmen Sie ansonsten die Standards und arbeiten Sie den Assistenten durch, bis die neue Seite erzeugt ist. Navigieren Sie dann im Page Designer zur gerade erzeugten Seite 10, dort in die Seitenattribute und dort zum Abschnitt Dialog mit den Eigenschaften des modalen Dialogs. Stellen Sie die Eigenschaft Chained auf No - denn dieser neue modale Dialog soll sich das Fenster gerade nicht mit dem Formular teilen (Abbildung 17).

Abbildung 17: Eigenschaft "Chained" im neuen modalen Dialog auf "No" setzen

Navigieren Sie dann wieder zur Startseite, öffnen Sie mit dem Formular den ersten modalen Dialog und klicken Sie dann auf die neue Schaltfläche, woraufhin sich der zweite modale Dialog öffnet (Abbildung 18).

Abbildung 18: Ein modaler Dialog öffnet einen anderen

Der nächste Schritt wäre nun, dass der Endanwender eine Zeile im Bericht klickt, woraufhin der modale Dialog geschlossen und eine Information über die gewählte Zeile zum Formular zurückgegeben wird. Navigieren Sie dazu nochmals im Page Designer zur Seite 10 und dort in die Eigenschaften der Berichtsspalte ENAME. Stellen Sie diese auf den Spaltentyp LINK um, hinterlegen Sie #ENAME# als Link Text, wählen Sie URL als Link Target aus und geben Sie den folgenden Javascript-Aufruf als Target-URL an.

javascript:apex.navigation.dialog.close(true, {'EMPNO': '#EMPNO!JS#'});

Abbildung 19: Die Spalte ENAME wird zum Link: Bei Klick schließt sich der modale Dialog

Der Javascript-Aufruf apex.navigation.dialog.close ist im Bereich der Application Express Javascript APIs dokumentiert. Neben dem Schließen des Fensters ist vor allem der zweite Parameter wichtig: APEX sendet beim Schließen des Dialogs ein Ereignis (Event) auf das man mit einer Dynamic Action reagieren kann. An dieses Event wird das Javascript-Objekt, welches als zweiter Parameter übergeben wurde, angehängt, so dass man in der dynamischen Aktion Zugriff darauf nehmen kann.

Wenn Sie den neuen Setup nun testen, schließt sich der zweite modale Dialog bei Klick auf eine Zeile bereits, es geschieht aber nichts weiter. Daher navigieren Sie nun im Page Designer zum ersten modalen Dialog, der Formularseite auf die Tabelle EMP. Dort wird nun die dynamische Aktion hinterlegt, die auf das Schließen des zweiten modalen Dialogs reagiert, die übergebene EMPNO entgegennimmt und das Element P3_MGR entsprechend setzt. Klicken Sie oberhalb des Navigationsbaums links das Blitz-Symbol an, um zu den dynamischen Aktionen zu gelangen. Öffnen Sie dann das Kontextmenü beim Eintrag Dialog closed und klicken Sie auf Create Dynamic Action (Abbildung 20).

Abbildung 20: Neue dynamische Aktion auf der Formularseite anlegen: On Dialog closed

APEX legt Ihnen die dynamische Aktion mit Defaults an - die Dinge, die Sie auf jeden Fall noch ändern müssen, werden rot markiert. Passen Sie zunächst im Property-Editor rechts den Namen der dynamischen Aktion und belassen Sie das Event im Bereich When bei Dialog closed. Als Selection Type wählen Sie Button aus und als Button nehmen Sie den vorhin erzeugten CHOOSE. Damit ist der Bereich, der die dynamische Aktion auslöst, fertig. Nun sollte auch eine der beiden roten Meldungen verschwunden sein (Abbildung 21).

Abbildung 21: Die dynamische Aktion wird ausgelöst, wenn ein Dialog geschlossen wurde

Klicken Sie dann auf das den im Navigationsbaum links noch rot markierten Eintrag, der mit Refresh benannt ist. Hier stellen Sie ein, was die dynamische Aktion tun soll. Nehmen Sie im Property Editor folgende Änderungen vor:

• Wählen Sie Set Value als Action im Bereich Identification aus.
• Im Bereich Settings wählen Sie Dialog Return Item bei Set Type aus und tragen EMPNO als Return Item ein.
• Im Bereich Affected Elements wählen Sie Item aus und legen P3_MGR als Element fest.
• Stellen Sie Fire On Page Load bei den Execution Options auf No.

Abbildung 22: Die dynamische Aktion setzt das Element P3_MGR mit dem ausgewählten Wert

Nun können Sie Ihre neue Modale Auswahlliste ausprobieren. Starten Sie mit der Startseite, die den Bericht auf die Tabelle EMP enthält. Klicken Sie in einer der Zeilen auf den Bleistift, um das Formular aufzurufen. Klicken Sie dann auf den neuen Button neben dem Element P3_MGR, um die modale Auswahlliste zu öffnen. Bei Klick auf einen Eintrag ändert sich im Formular das Element P3_EMPNO und der zweite modale Dialog wird geschlossen, so dass der Fokus wieder auf dem ersten, dem Formular liegt. Ein Klick auf den Button Save speichert die Zeile schließlich ab und schließt auch den ersten modalen Dialog, so dass man sich wieder auf der Startseite befindet. Die folgenden 3 Abbildungen zeigen den Prozess.

Abbildung 23: KING hat keinen Manager

Abbildung 24: ALLEN wird als neuer Manager ausgewählt

Abbildung 25: Die EMPNO von ALLEN wurde als P3_MGR ins Formular übernommen

Abbildung 26: Die Änderung wurde in der Tabelle gespeichert

Exkurs: Formular-Layout weiter optimieren

Besonders Gelungen kann man das Formular mit dem neuen Button zur Auswahl eines MGR sicherlich nicht nennen. Eleganter wäre es ja, wenn kein Button da wäre und der modale Dialog sich öffnete, sobald man in das Textfeld für den MGR klickt. Das ist mit drei Änderungen ganz leicht zu realisieren.

1. Geben Sie dem Button eine statische ID - bspw. BT_CHOOSE_MGR.
   

   Abbildung 27: Static ID für den Button vergeben

2. Erzeugen Sie eine Dynamic Action, die beim Seitenladen auslöst (On Page Load) und welche den Button versteckt (Hide).
3. Eine weitere Dynamic Action soll ausgelöst werden, wenn das Element P3_MGR den Fokus bekommt. Als Event nehmen Sie also Get Focus, Item als Selection Type und P3_MGR als Item. Bei Action tragen Sie Execute Javascript Code ein und als Javascript Code hinterlegen Sie $("#BT_CHOOSE_MGR").click(). Stellen Sie dann noch (das ist wichtig) Fire On Page Load auf No.

Der Button ist also noch vorhanden, aber nicht mehr sichtbar. Sobald der Fokus auf das Eingabefeld für den MGR gelegt wird, wird der "unsichtbare" Button programmatisch "geklickt."

Fazit

Modale Dialoge in APEX bieten weit mehr Möglichkeiten an, als das einfache Aktivieren und Deaktivieren. Mit Hilfe von Attributen kann das Erscheinungsbild beeinflusst werden und mit Hilfe der Javascript-Funktionen und mit dynamischen Aktionen lassen sich auch komplexere Szenarien wie eine "Super-Auswahlliste" realisieren - und das alles mit APEX Bordmitteln. Die Möglichkeiten der Javascript-API gehen sogar noch weiter. So gibt es einen API-Aufruf zum Öffnen eines modalen Dialoges, so dass man auch Nicht-APEX-Seiten als modale Dialoge in eine APEX-Seite einbinden kann - es gibt fast keine Grenzen.

Zurück zur Community-Seite