Template Options: Was ist das?

Seit März 2015 steht APEX 5.0 auf dem Demoserver apex.oracle.com bereit - Zeit, sich die neuen Funktionen etwas genauer anzusehen. In diesem Community-Tipp geht es um die neuen Template Options, mit denen sich das Aussehen von APEX-Komponenten noch besser beeinflussen lässt als vorher. Das neue Universal Theme macht von diesen Template Options bereits regen Gebrauch. Schauen wir uns zunächst die vorhandenen Template Options an. Erzeugen Sie in APEX 5.0 eine neue Applikation mit einer Seite und einer Region vom Typ Static Content (Abbildungen 1 und 2).

Abbildung 1: Erzeugen einer neuen Region "Static Content" mit dem Page Designer

Abbildung 2: Die Anwendungsseite "in Action"

Klicken Sie nun im Page Designer auf Template Options (Abbildung 3).

Abbildung 3: "Template Options" auswählen

Daraufhin öffnet sich ein Fenster zur Konfiguration des Layouts dieser Region (Abbildung 4).

Abbildung 4: Dialog "Template Options"

Nehmen Sie nun einige Änderungen vor - stellen Sie beispielsweise das Attribut Header auf Hidden oder den Style auf Remove Borders. Starten Sie die Seite danach neu. Sie sollte nun wie in Abbildung 5 aussehen (die Titelleiste ist weg).

Abbildung 5: Anwendungsseite mit veränderten Template Options

Template Options stehen für alle Templates aller Komponententypen bereit; es lohnt sich wirklich, für jede Komponente dort einen Blick hineinzuwerfen. Ein großer Teil der Darstellungsvielfalt des Universal Theme ist mit Template Options realisiert. So lassen sich Schaltflächen über Template Options einfärben und deren Bedeutung hervorheben (Abbildung 6) - probieren Sie es aus!

Abbildung 6: Template Options für eine Schaltfläche

Technisch sind Template Options mit CSS-Klassen verknüpft - wird eine solche Option ausgewählt, wird die verbundene CSS-Klasse in den HTML-Code der Region aufgenommen. Das wollen wir uns nun näher ansehen und dabei auch eigene Template Options erstellen. Ziel ist es, Template Options zum Einfärben des Regionstitels bereitzustellen. Abbildung 7 zeigt, wie die neuen Template Options für die Region Static Content dann aussehen sollen - die Template Options Red title, Green title und Blue title kommen nicht von APEX; sie werden im folgenden von Ihnen hinzugefügt.

Abbildung 7: Das Ziel: Eigene Template Options für die Region "Static Content"

Exkurs: Ist das Universal Theme "Read Only"?

Wenn man an den Einstellungen des Universal Theme oder an den einzelnen Templates Änderungen vornehmen möchte, merkt man schnell, dass dies anscheinend nicht möglich ist - alles ist Read Only.

Der Grund ist, dass das Universal Theme einer APEX-Anwendung mit der "Vorlage" in der APEX-Engine synchronisiert ist - es verwendet den schon aus früheren APEX-Versionen bekannten Subscribe Modus. Der Vorteil ist, dass Änderungen des Universal Theme in künftigen APEX-Versionen oder Patchsets so automatisch auf bestehende Anwendungen übertragen werden können: Bestehende APEX-Anwendungen können (und das ist neu in APEX 5.0) also auch von künftigen Verbesserungen im Universal Theme profitieren.

Das bedeutet allerdings, dass man die vorhandenen Bestandteile nicht ändern kann. Man kann allerdings neue Komponenten-Templates erzeugen und dem Theme neue Dateien hinzufügen; kurz gesagt: Das Anwendungs-Theme kann zwar nicht verändert, aber erweitert werden.

Wer das Theme umfassend ändern möchte, kann die Subscription aufheben - dazu navigiert man in dem Gemeinsamen Komponenten zu den Themes, dort zum Eintrag mit dem Universal Theme und dann in den Bereich Theme Subscription. Ein Klick auf den Button Unsubscribe bringt zunächst eine Warnung - ein nochmaliger Klick auf Unsubscribe Theme hebt die Synchronisierung auf. Alle Komponenten des Themes können dann verändert werden. Änderungen am Universal Theme in künftigen APEX-Versionen können jedoch nicht mehr automatisch übernommen werden.

Subscription des Universal Theme aufheben

Das Aufheben der Subscription sollte man nur durchführen, wenn man vorhat, das Theme wirklich umfassend zu ändern. Solange man nur kleinere Erweiterungen vornehmen möchte, ist es besser, die Subscription bestehen zu lassen und die Templates, die man verändern möchte, neu zu erzeugen. Dies werden wir auch in diesem Tipp tun. Der Vorteil dieses Ansatzes ist, dass die unveränderten Templates nach wie vor von den Vorteilen der Subscription profitieren können.

Ein neues Template erzeugen - mit neuen Template Options

Navigieren Sie dazu zu den gemeinsamen Komponenten und dort zum Bereich Templates. Filtern Sie die Übersicht nach Regions-Templates und klicken Sie in der Zeile des Regionstemplate Standard rechts auf das "Kopieren"-Symbol (Abbildung 8).

Abbildung 8: Das Regionstemplate Standard wird kopiert

Geben Sie ihrem neuen Template im darauf folgenden Dialog einen Namen (Neues Template!) und klicken Sie auf Copy. Daraufhin sehen Sie Ihr neues Template in der Liste. Klicken Sie darauf - sie gelangen dann zur Bearbeitungsseite für das Template (Abbildung 9).

Abbildung 9: Das neue Regions-Template kann bearbeitet werden

Der Abschnitt Template Options (mitsamt der Schaltfläche Add Template Option) ist schnell zu erkennen. Unterhalb der auf Abbildung 9 dargestellten Defaults werden die bereits vorhandenen Template Options gelistet (Abbildung 10). Hier ist deutlich sichtbar, dass eine Template Option mit einer oder mehreren CSS-Klassen verknüpft ist.

Abbildung 10: Bereits vorhandene Template Options

Klicken Sie nun auf die Schaltfläche Add Template Option. Es öffnet sich ein Dialog zum Erstellen einer neuen Template Option. Füllen Sie diesen, wie in Abbildung 11 dargestellt, aus.

Abbildung 11: Eine neue Template Option erzeugen

• Group: Header
• Display Name: Red Title
• Option Identifier: RED_TITLE
• CSS classes: myoption-title-red

Wichtig ist vor allem die Gruppe und die CSS-Klasse. Innerhalb einer Gruppe kann der Entwickler später genau eine Template Option auswählen - für die Gruppe Header sind bereits die Optionen Hidden und Hidden, but accessible vorhanden - da passen die neuen Optionen zum Einfärben der Überschrift sehr gut dazu. Wählt man keine Gruppe aus, so werden die Optionen dem Entwickler als Checkboxes präsentiert, die er dann einzeln ein- und ausschalten kann. Wenn sich verschiedene Template Options also gegenseitig ausschließen (wie es beim Einfärben des Titels der Fall ist), sollten Sie einer Gruppe zugeordnet werden.

Die Namen der CSS-Klassen können Sie frei wählen; stellen Sie aber sicher, dass der Name eindeutig ist und nicht mit etwaigen anderen CSS-Klassen kollidiert.

Nachdem Sie die erste Klasse erzeugt haben, erzeugen Sie noch zwei weitere für einen blauen und einen grünen Titel. Tragen Sie als CSS-Klassen entsprechend myoption-title-blue und myoption-title-green ein.

Navigieren Sie nach dem Speichern zurück zum Page Designer. Stellen Sie das Template Ihrer Region vom Typ Static Content von Standard auf Ihr neues Template um (Abbildung 12).

Abbildung 12: Regions-Template ändern

Klicken Sie danach nochmals auf die Template Options und öffnen Sie die Auswahlliste für den Header (Abbildung 13). Ihre neu angelegten Template Options sind nun enthalten. Wählen Sie eine aus, speichern Sie ab und starten Sie die Seite neu ...

Abbildung 13: Auswahl einer neuen Template Option

Nach dem Starten der Seite bemerken Sie noch keinen Unterschied - und das ist logisch - denn Sie haben Ihrer Region zwar - per Template Option - eine neue CSS-Klasse hinzugefügt; diese ist aber noch nirgends definiert. Abbildung 14 zeigt, dass die CSS-Klasse tatsächlich im HTML-Code enthalten ist.

Abbildung 14: HTML-Code der Region - die Template Option ist als CSS-Klasse vorhanden

Die CSS-Klassen der Template Options werden im HTML-Code immer beim Platzhalter #REGION_CSS_CLASSES# eingesetzt. Abbildung 15 zeigt diese Stelle in der Template-Definition.

Abbildung 15: #REGION_CSS_CLASSES# in der Template-Definition

Bei Implementierung der CSS-Klassen muss man mit CSS-Selektoren arbeiten, um die richtigen HTML-Attribute zu "treffen". Der CSS-Code für unsere drei Klassen zum Einfärben des Titels sieht wie folgt aus.

/*
 Ausgehend vom DIV-Tag, welches den Platzhalter #REGION_CSS_CLASSES# 
 enthält, werden in der Hierarchie die HTML-Tags <h2> mit der CSS-Klasse 
 "t-Region-title" selektiert.

 Das Attribut "!important" bedeutet, dass diese Einstellung anderen, 
 ggfs widersprechenden CSS-Anweisungen vorgehen soll.

 Diese bekommen dann ein CSS-Attribut "color" zum Einfärben zugewiesen
 */

.myoption-title-green h2.t-Region-title {
  color: green !important;
}
.myoption-title-red h2.t-Region-title {
  color: red !important;
}
.myoption-title-blue h2.t-Region-title {
  color: blue !important;
}

Dieser CSS-Code muss nun ebenfalls hinzugefügt werden; das geht natürlich nicht beim Region-Template - ein besserer Ort ist das Seitentemplate. Da die Subscription des Themes nicht aufgehoben wurde, kann der CSS-Code nicht einfach dem vorhandenen Seitentemplate hinzugefügt werden. Für diesen Tipp werden wir das Seiten-Template, welches unsere Anwendungsseite nutzt, also kopieren und dieser Kopie den CSS-Code hinzufügen. Navigieren Sie also in den Gemeinsamen Komponenten zu den Templates und stellen Sie den Filter in der Übersicht auf Page (für Seitentemplates) ein.

Abbildung 16: Vorhandene Seitentemplates

Klicken Sie (wie schon vorhin beim Regions-Template) in der Zeile des Templates Standard auf das "Kopieren"-Symbol ganz rechts. Im darauf folgenden Dialog vergeben Sie einen neuen Namen und klicken auf Copy.

Abbildung 17: Seitentemplate "Standard" kopieren

Wählen Sie dann die neu entstandene Kopie in der Übersicht aus, navigieren Sie zum Abschnitt Cascading Style Sheet und kopieren Sie obigen CSS-Code, wie in Abbildung 18 dargestellt, in den Bereich Inline.

Abbildung 18: CSS-Code ins neue Seitentemplate übertragen

Speichern Sie das Template mit Apply Changes ab und navigieren Sie in den Gemeinsamen Komponenten dann zum Bereich Themes - und dort in das Universal Theme.

Abbildung 19: Zum Anwendungstheme "Universal Theme" navigieren

Im Bereich Component Defaults stellen Sie das Seitentemplate ("Page") von Standard auf das neue Standard New um. Alle Seiten, die das Standard-Seitentemplate des Universal Theme verwenden, bekommen nun das neue Template.

Abbildung 20: Das neue Template "Standard New" wird zum Default-Seitentemplate

Speichern Sie das Ganze mit einem Klick auf Apply Changes ab und starten Sie die Seite neu. Die Regionsüberschrift ist nun rot.

Abbildung 21: Die neue Template Option ist wirksam

Das Ändern der Farbe auf Grün oder Blau erreicht man nun einfach mit einer Änderung der entsprechenden Template Option, wie die folgenden Abbildungen zeigen.

Abbildung 22: Setzen der Template Option "Green Title"

Abbildung 23: Setzen der Template Option "Blue Title"

Fazit

Die in APEX 5.0 neuen Template Options erlauben eine wesentlich bessere Strukturierung von CSS-Eigenschaften eines APEX-Templates. CSS-Klassen können einem Template nun als Ein- und Ausschaltbare Template Options mit einem sprechenden Namen und Hilfetext hinzugefügt werden. Bei Nutzung des Templates können die Optionen dann bequem per Auswahlliste aktiviert oder deaktiviert werden.

Das erlaubt nicht nur eine noch bessere Trennung zwischen Template-Design und Template Verwendung durch den APEX-Entwickler, die Template Options finden sich darüber hinaus im APEX-Data Dictinary wieder, so dass man nun auch gezielt und strukturiert nach verwendeten Template Options suchen kann.

Zurück zur Community-Seite