von Tobias Arnhold, Tobias Arnhold IT Consulting, Dresden

In diesem Beispiel zeige ich ihnen, wie Sie ein Dynamic Action Plugin erstellen können. Es gibt vier verschiedene Plugin-Typen:

• Region Type Plugins
• Item Type Plugins
• Dynamic Action Plugins
• Process Type Plugins

Carsten Czarski beschrieb bereits, was Sie generell über APEX Plugins wissen sollten und wie Sie ein Region Plugin erstellen können: Details erfahren Sie in diesem Community-Tipp Sobald ein Plugin in der Anwendung installiert ist, steht es dem Anwendungsentwickler zusätzlich zu den eingebauten Komponententypen zur Verfügung. Ist demnach ein Dynamic Action-Plugin installiert, so steht dieses bei der Auswahl einer Dynamic Action als Event oder Action zur Verfügung (Abbildung 1).

Abbildung 1: Neuer Typ "[Plug-in]"

Der Vorteil von Dynamic Actions liegt darin, bestehenden Javascript-Code im Page Header lesbar und nachvollziehbar innerhalb des APEX Page Builders zur Verfügung zu stellen. Durch ein Dynamic Action Plugin können Sie diese nun beliebig oft innerhalb ihrer Anwendungen verwenden, ohne unvorteilehafte Copy/Paste Operationen am Code. Die generellen Vorteile von Plug-Ins hat Carsten in seinem Community-Tipp ja bereits ausreichend gut erklärt. Diese treffen bei Dynamic Action Plugins ebenfalls zu.

Ein eigenes Plugin entwickeln

Wir erstellen ein Dynamic Action-Plugin namens "PopUp Box". Deren Aufgabe es ist, dynamisch beliebige Meldungen als jQuery PopUp während der Laufzeit anzuzeigen.

Dieses PopUp wird normalerweise wie folgt gestartet:

   var popUpBox = $('<div></div>')      /* Erstellt dynamisch ein DIV element */
   .html('Hello World PopUp Box')       /* Inhalt, kann Rückgabewert einer APEX Funktion sein */
   .dialog({autoOpen: true,             /* Automatisch oeffnen true/false */
            resizable: false,           /* Groesse kann veraendert werden true/false */
            title: 'Information',       /* Title der Box */
            width: 350                  /* Breite */
          });

Navigieren Sie also nochmals zu den Gemeinsamen Komponenten und dort zu den Plugins. Anstelle von Importieren klicken Sie nun die Schaltfläche Erstellen. Sie sehen dann den Dialog zum Erzeugen eines neuen Plugins (Abbildung 2).

Abbildung 2: Ein neues Plugin erstellen

Dass ein Plugin zwei Namen hat, fällt wahrscheinlich jedem als erstes auf. Das erste Eingabefeld Name ist der Name, der dem APEX-Entwickler angezeigt wird, wenn er eine neue Dynamic Action erstellt. Der zweite Internal Name dient der globalen Eindeutigkeit. Es ist vorgesehen und beabsichtigt, dass Plugins in der Community geteilt werden - es ist also wahrscheinlich, dass ein Plugin, das in einem Unternehmen entwickelt wurde, woanders eingesetzt wird. Um die daraus entstehenden potenziellen Namenskonflikte zu verhinden, gibt es den internen Namen. Am besten halten Sie sich hier an das URL-Konzept - für unser neues Plugin wählen Sie also PopUp Box als Name und COM.AAW.POPUPBOX als internen Namen. Als Typ wählen Sie Dynamic Action aus. Als Kategorie verwenden Sie bitte Notification (Meldung). Die Kategorie dient nur der Gruppierung in der Anzeigeauswahl von Dynamic Actions.

Im nächsten Abschnitt kann der Code über den APEX-Subscription-Mechanismus von einem anderen Plugin abonniert werden. Dieser Mechanismus erlaubt das Führen einer Master-Anwendung (mit Plugins), deren Änderungen dann auf die abonnierenden Anwendungen übertragen werden können. Das ist sehr nützlich, wenn ein Plugin in mehreren Anwendungen verwendet werden und dann bspw. eine neue Version eingespielt werden soll. Das aktualisierte Plugin kann dann mit einem Klick auf alle Anwendungen übertragen werden. Mehr zum Subscription-Feature in diesem Community-Tipp.

Das nächste, wichtige Feld ist der PL/SQL Code, der in diesem Fall für das Rendering der Region verantwortlich ist. Da das Plugin sich an die APEX-Infrastruktur anpassen muss, ist für die verschiedenen Plugin-Typen eine ganz bestimmte Funktionssignatur vorgeschrieben. Für ein Regions-Plugin muss mindestens die Render-Funktion wie folgt ausprogrammiert werden.

function {name of function} (
    p_dynamic_action  in apex_plugin.t_dynamic_action,
    p_plugin          in apex_plugin.t_plugin)
    return apex_plugin.t_dynamic_action_render_result

Den Namen der Funktion selbst können Sie dabei frei wählen. Er muss nur unterhalb im Bereich Callbacks als Render Function eingetragen werden. Hinterlegen Sie also den folgenden PL/SQL-Code:

-- Developed by Tobias Arnhold - http://apex-at-work.blogspot.com/
FUNCTION render_popup_box (p_dynamic_action IN apex_plugin.t_dynamic_action, p_plugin IN apex_plugin.t_plugin)
  RETURN apex_plugin.t_dynamic_action_render_result
AS
  -- Return variable
  l_result                      apex_plugin.t_dynamic_action_render_result;

  -- Save plugin-parameter in local variables
  l_popup_text           apex_application_page_regions.attribute_01%type := p_dynamic_action.attribute_01;
  l_popup_title          apex_application_page_regions.attribute_02%type := p_dynamic_action.attribute_02;
  l_popup_width          apex_application_page_regions.attribute_03%type := p_dynamic_action.attribute_03;
  l_popup_height         apex_application_page_regions.attribute_04%type := p_dynamic_action.attribute_04;

  
  -- Variables for javascript parts
  l_complete_code varchar2(2000);

begin
/* During plug-in development it's very helpful to have some debug information */
  IF APEX_APPLICATION.g_debug THEN
    apex_plugin_util.debug_dynamic_action (p_plugin => p_plugin, p_dynamic_action => p_dynamic_action);
  END IF;

/* Escaping der Parameter */
  l_popup_text          := apex_plugin_util.escape(l_popup_text, true);
  l_popup_title         := apex_plugin_util.escape(l_popup_title, true);
  l_popup_width         := apex_plugin_util.escape(l_popup_width, true);
  l_popup_height        := apex_plugin_util.escape(l_popup_height, true);

/* Function declaration */
  l_complete_code := 'function(){'||chr(10);
  
/* Code definition*/
  l_complete_code := l_complete_code || 'var popUpBox = $("<div></div>") ' || chr(10);
  l_complete_code := l_complete_code || '   .html("'||l_popup_text||'")  ' || chr(10);
  l_complete_code := l_complete_code || '   .dialog({autoOpen: true,  ' || chr(10);
  l_complete_code := l_complete_code || '            resizable: false, ' || chr(10);
  l_complete_code := l_complete_code || '            modal: true, ' || chr(10);
  l_complete_code := l_complete_code || '            title: "'||l_popup_title||'",  ' || chr(10);
  l_complete_code := l_complete_code || '            width: '||l_popup_width||',  ' || chr(10);
  l_complete_code := l_complete_code || '            height: '||l_popup_height||'  ' || chr(10);
  l_complete_code := l_complete_code || '          });  ' || chr(10);
  l_complete_code := l_complete_code || '$(".ui-dialog-content").height('||l_popup_height||'); ' || chr(10);
  
/* Finish Code */
  l_complete_code := l_complete_code || '}';

  l_result.javascript_function := l_complete_code;
  return l_result;
end render_popup_box;

Tragen Sie danach render_popup_box als Render Function Name ein, navigieren Sie nach oben und klicken Sie auf Erstellen. Wenn Ihr PL/SQL-Code fehlerfrei ist, werden Sie wieder auf die gleiche Seite verzweigt, unterhalb der Callbacks können Sie aber nun Standard-Attribute und Benutzerdefinierte Attribute (Plugin-Parameter) Ihres Plugins festlegen und Dateien hochladen.

Im PL/SQL-Code werden zu Beginn vier Parameter referenziert. Ihr PL/SQL-Code bekommt alle Informationen über Attribute und den Kontext, aus dem das Plugin heraus ausgeführt wird, in den Parametern p_dynamic_action und p_plugin übergeben. Das APEX-Team hat sich hier für eine Record-Struktur (apex_plugin.t_dynamic_action bzw. apex_plugin.t_plugin) entschieden. Aus dieser werden die konkreten Parameter ausgelesen und der besseren Übersichtlichkeit halber in lokale PL/SQL-Variablen übernommen. Wir müssen nun die auszuführende Javascript Funktion definieren. Dazu verwenden wir eine Variable namens: l_complete_code diese wir dem Funktionsaufruf zuweisen: l_complete_code := 'function(){' Nun packen wir nur noch unseren oben benannten Code mit ersetzten Parametern in l_complete_code rein und schließen den Funktionaufruf ab: l_result.javascript_function := l_complete_code; return l_result; Klicken Sie als als nächstes im Bereich Benutzerdefinierte Attribute auf die Schaltfläche "Add Attribute" (Abbildung 3), um die vier Parameter einzurichten. Und geben Sie wie in Abbildung 4 beschrieben die nötigen Parameter ein:

Abbildung 3: Attribut definieren

Abbildung 4: Der erste Plugin-Parameter wird festgelegt

Abbildung 4 zeigt die Einrichtung des ersten Parameters. Mit diesem kann der Entwickler den PopUp Text festlegen. Legen Sie analog die weiteren Parameter an: PopUp Titel (Typ: Text), PopUp Breite (Typ: Number), PopUp Höhe (Typ: Number).
Wenn alles fertig konfiguriert wurde, dann sollte die Übersicht wie folgt aussehen:

Abbildung 5: Attributübersicht

Sie können zu jedem Parameter einen Hilfetext vergeben - und es ist auch sehr empfehlenswert, hier etwas Zeit zu investieren. Denn ein Plugin ist nicht mehr und nicht weniger als ein Code-Modul, bei dem Sie davon ausgehen, dass es eine andere Person verwenden wird. Zuviel Dokumentation kann es da also gar nicht geben. Wenn Sie alle Parameter definiert haben, können Sie Ihr Plugin mit der Schaltfläche Änderungen anwenden oben rechts abspeichern.

Abbildung 6: Dynamic Action erstellen

Definieren Sie nun das gewünscht Event auf das die Dynamic Action reagieren soll. Beispielsweise: Page Load

Abbildung 07: Dynamic Action Event definieren

Nachdem Sie das Event definiert haben, kommt der Augenblick an dem Sie ihr erstelltes Plugin das erste mal auswählen können. Unter der Gruppe Notification wählen Sie bitte: PopUp Box [Plug-In] aus

Abbildung 08: PopUp Box [Plug-In] auswählen

Nach dem Plugin ausgewählt wurde, können Sie die Standardeinstellungen (Abbildung 9) ändern und anschließend die Dynamic Action erstellen.

Abbildung 09: Standardeinstellungen ändern

Starten Sie die Seite und unser neu erstellte PopUp Box sollte jetzt erscheinen.

Abbildung 10: PopUp Box in Anwendung

Fazit

Wie Sie sehen ist es gar nicht so schwer ein Dynamic Action Plugin zu erstellen. Hier finden Sie die Beispielanwendung: http://apex.oracle.com/pls/apex/f?p=AAW_PLUGINS:POPUP_BOX

Unter www.apex-plugin.com finden Sie weitere Plugins von mir. Beispielsweise das UILayout Plug-in das ein dynamisches UserInterface bereitstellt. Diese Dynamic Action Plugins sind weitaus komplexer, aber basieren alle auf der selben Codebase. Das PopUp Box Plugin werde ich in den kommenden Tagen unter www.apex-plugin.com zum Download bereitstellen.

Im Moment lohnt es sich wahrscheinlich am Meisten, bestehende Javascript Funktionen die Sie in mehreren Anwendungen verwenden in ein APEX Plugin zu migrieren, um so eine Menge Entwicklungs-Overhead zu sparen.

Zurück zur Community-Seite