APEX Javascript APIs

07.
Januar
2019
Veröffentlicht von: Andreas Mößel

Sonderfälle in der APEX-Anwendungsentwicklung benötigen manchmal besondere Funktionen, die APEX nicht zur Verfügung stellt. Auf Clientseite kann man das mit Javascript lösen. Hierzu gibt es von Oracle mit den dokumentierten Javascript APIs eine Hilfestellung.

Javascript? Brauch ich nicht.

Oracle’s APEX Anwendungen können von Haus aus schon sehr viel. Viele Funktionen, die man für so eine Anwendung brauchen kann, können einfach und überschaubar verwendet werden, ohne dass eine andere Programmiersprache verwendet werden muss. Aber immer wieder stößt man an die Grenzen von APEX’s Funktionalitäten. Zum Beispiel, wenn es um einen regelmäßigen Automatismus zur Erneuerung eines Berichtes geht. An diesen Stellen kann man dann mit Javascript eingreifen.

Dokumentierte Javascript APIs

Diese APIs bilden den Grundstock an Funktionen, die man für die Anwendung verwenden kann. Als APEX 5 auf den Markt kam, gab es nur ein paar dokumentierte APIs. Aber je komplexer die Anwendungen wurden, desto größer wurde der Wunsch nach mehr Kontrolle und Möglichkeiten zum manuellen Eingreifen in den Anwendungsablauf. Oracle hat diesen Wunsch erhört und erweitert nun mit jeder neuen Version die Anzahl der dokumentierten APIs.

Neue APIs mit 18.2

Es gibt schon länger dokumentierte Namespaces, aber neu hinzugekommen sind die APIs für Widgets, welches Elemente sind, mit denen der Benutzer interagieren kann, wie anpassbare Berichte, Schaltflächen und Scrollbars:

  • grid
  • iconList
  • interactiveGrid
  • menu
  • recordView
  • tableModelView
  • treeView

Zusätzlich wurden auch diese Namespaces beschrieben: apex.actions und apex.models

Ein Blick in das Interactive Grid Widget

Öffnet externen Link in neuem FensterHier findet man die Liste der APIs. Mit einem Blick in die Dokumentation für das Interactive Grid Widget sieht man, was es zu bieten hat.

Der erste Eintrag unter den „Options“ ist „editable“, eine Eigenschaft die man leicht beim Interactive Grid einstellen kann. Aber was ist, wenn man den Bericht nur unter bestimmten Bedingungen editierbar machen will? Dann könnte einem genau das weiterhelfen.

Hierfür wird das „JavaScript Initialization Code“-Attribut des Interactive Grids benötigt, welches eine Funktion in folgendem Format entgegennimmt:

function( options ) {
    //Optionen verändern
    return options;
}

Also ergänzt man diese Funktion nach seinen Vorstellungen, so dass sie am Ende vielleicht folgendermaßen aussieht:

function( options ) {
    if (app_user = 'Harald') {
       options.editable = false;
    }
    return options;
}

Es ist natürlich nur ein einfaches Beispiel: Das Grid ist normalerweise bearbeitbar, nur z. B. für den Benutzer Harald nicht. Die Variable „app_user“ muss vorher noch bei den globalen Variablen und Funktionen der Seite deklariert und mit ‚&app_user.‘ gefüllt werden.

In der Dokumentation gibt es noch viel mehr Optionen und sogar Events, die spezifisch für das Interactive Grid sind, und Methoden wie „refresh“ oder „focus“ werden beschrieben:

Namespaces

Ein anderer Blick sollte zu den Namespaces gehen, die genauso interessant sind wie die Widgets:

  • apex
  • apex.actions
  • apex.da
  • apex.debug
  • apex.event
  • apex.item
  • apex.lang
  • apex.message
  • apex.model
  • apex.navigation
  • apex.navigation.dialog
  • apex.navigation.popup
  • apex.page
  • apex.region
  • apex.server
  • apex.util
  • apex.util.delayLinger
  • apex.widget

An den Namen dieser Namespaces kann man schon erahnen, worum sie sich handeln:

Z. B. hat apex.da etwas mit dynamischen Aktionen zu tun, apex.event mit Events und apex.navigation mit Seitennavigation.

Der APEX Namespace

Unter dem einfachen APEX Namespace gibt es Beschreibungen und Beispiele üblicher APEX-Events, wie die „apexafterrefresh“- oder „apexbeforpagesubmit“-Events. Diese sind equivalent zu den Events „After Refresh“ und „Before Page Submit“ bei den dynamischen Aktionen. Das bedeutet, dass man diese Funktion als reines Javascript nachbauen kann, wenn man es benötigt.

Ein anderes Event „apexpagesubmit“ triggert direkt, bevor eine Seite endgültig eingereicht wird und bietet so zum Beispiel eine letzte Möglichkeit, die Werte von Items vor allen Prozessen zu verändern.

Der sich drehende Kreis

Hier ein konkreteres Beispiel mit Hilfe des apex.widget Namespace:

Dieser bietet eigentlich nur zwei Funktionen an: initPageItem, welches veraltet und mit „deprecated“ markiert ist und waitPopup.

Mit der waitPopup-Funktion setzt man die Warte-Animation von APEX. Die graue, durchsichtige Fläche mit dem sich drehenden Kreis in der Mitte verhindert, dass ein ungeduldiger Benutzer wild herumklickt. Sie signalisiert dem Benutzer: Hier tut sich was, aber es dauert.

Das ist das Javascript, das benötigt wird, um den Kreis zu setzen:

Var popup = apex.widget.waitPopup();

Und so entfernt man ihn wieder:

Popup.remove();

Die waitPopup-Funktion gibt ein Objekt, das eine Löschfunktion für das Popup enthält, zurück. Das Objekt muss in einer Variable gespeichert werden, damit am Ende das Popup wieder entfernt werden kann. Zwischen diesen beiden Aufrufen findet dann der dauernde Prozess oder eine langes Javascript statt.


Fazit

Auch wenn man es nicht immer in APEX-Anwendungen benötigt, sind APEX APIs eine wertvolle Ergänzung für Entwickler. Man hat damit die Möglichkeit, APEX-Funktionalitäten mit Javascript nachzubauen oder in diese eingreifen zu können.
Die Dokumentation bietet einen guten Überblick und ist eine gute Anleitung.

Jede Menge Know-how für Sie!

In unserer Know-How Datenbank finden Sie mehr als 300 ausführliche Beiträge zu den Oracle-Themen wie DBA, SQL, PL/SQL, APEX und vielem mehr.
Hier erhalten Sie Antworten auf Ihre Fragen.