|
Oracle BI Publisher Tipp
 Verwendung von
Sub-Templates
|
|
Tauchen in einer
Vielzahl von Berichten immer wieder dieselben identischen
Layoutbestandteile
wie z.B. der Berichtskopf mit der Firmenanschrift und dem Logo auf,
kommt
schnell der Wunsch auf, diese gleichen Bestandteile aus den einzelnen
Berichten
herauszunehmen und stattdessen an zentraler Stelle zu verwalten.
Änderungen an
diesen Elementen müssten dann nur noch an einem einzigen Ort
vorgenommen werden
und würden automatisch in alle Berichte übernommen.
BI Publisher
bietet als Lösung hierfür die Verwendung von
Sub-Templates an. In Sub-Templates
werden Ausschnitte eines Berichtslayouts definiert, die an
gewünschter Stelle
eingebunden werden können.
Hinweis:
Einige der beschriebenen Features benötigen BI Publisher 10.1.3.4.0 oder 10.1.3.4.1 mit dem aktuellsten Patch-Set von Oracle Support (aktuell letzter Stand Juni 2010). Die unter oracle.com verfügbaren Versionen 10.1.3.4.0/10.1.3.4.1 enthalten die notwendigen Patches zum jetzigen Zeitpunkt nicht!
Wie werden Sub-Templates erstellt und eingebunden?
Sub-Templates
können in der gewohnten Syntax der RTF-Templates erstellt
werden.
Damit Sub-Templates in mehreren Berichten verwendet werden
können, sollten sie in einem eigenen RTF-Dokument hinterlegt
werden.
Schritt 1
Zuerst muss das Sub-Template
definiert
werden, z.B. in einer eigenen Datei subtemplates.rtf.
Syntax:
<?template:Sub-Template-Name?>
Inhalt des Sub-Templates, z.B. der Berichtskopf mit Logo
<?end template?>
Der Sub-Template-Name muss einzigartig sein und wird für die spätere Einbindung in die Layout-Templates der gewünschten Berichte benötigt.
Schritt 2
Wurde das gewünschte
Sub-Template in einer separaten Datei definiert, muss diese im
Ziel-RTF-Template eingebunden werden.
Syntax:
<?import:http://pfad/subtemplates.rtf?> (Zugriff über HTTP)
oder
<?import:file:///pfad/subtemplates.rtf?> (Zugriff über das Dateisystem)
Nach diesem Schritt können die Sub-Templates aus der separaten
Datei verwendet werden.
Es können mehrere externe Dateien eingebunden werden.
Wichtige Hinweise:
Die Importanweisungen
müssen vor allen anderen Anweisungen erfolgen, am besten an
erster Stelle im Layout-Template.
Beispiel korrekte Reihenfolge:
<?import:file:///C:\subtemplate.rtf?>
<?param@begin:irgendein_parameter;’test’?>
Beispiel falsche Reihenfolge:
<?param@begin:irgendein_parameter;’test’?>
<?import:file:///C:\subtemplate.rtf?>
=> Letzteres führt im Template-Builder zum Fehler:
oracle.xdo.parser.v2.XMLParseException: The 'import'
element children must precede all other element children of an
'stylesheet' element.
Der angegebene Pfad zur Datei
muss von der BI-Publisher-Instanz aus erreichbar sein.
<?import:file:///C:\bip\subtemplate.rtf?> mag im lokalen
Template-Builder einwandfrei funktionieren, auf dem BI-Publisher-Server
kann aber ein ganz anderer Pfad benötigt werden, sei es wegen
einer anderen Ordnerstruktur oder wegen eines anderen Betriebsystems.
Relative Pfadangaben funktionieren in der Regel nicht, geben Sie immer den kompletten Pfad an.
Achten Sie beim Zugriff
über das Dateisystem (file) bitte unbedingt auf den 3-fachen
Slash (///):
<?import:file:///…?>
<?import:file://C:\bip\subtemplate.rtf?> (2 statt 3
Slashes) zum Beispiel würde unter Windows zu diesem Fehler
führen:
java.net.UnknownHostException: C
Schritt 3
Um ein Sub-Template zu verwenden,
muss an der gewünschten Ausgabestelle folgender Befehl
eingefügt werden:
<?call:Sub-Template-Name?>
Schritt 4
BI-Publisher-Server: Damit der
Import aus Schritt 2. funktioniert, muss der Bericht noch entsprechend
konfiguriert werden. Unter Konfigurieren > FO-Verarbeitung ist
die Option „Externe Referenzen deaktivieren“ auf
„Aus“ zu setzen. Die Voreinstellung
„Ein“ verweigert den Zugriff auf die im
<?import:…?> angegebene Datei und damit auf
die Sub-Templates.
Hinweis: In älteren Builds heißt die Option fälschlicherweise "Externe Referenzen aktivieren" statt "...deaktivieren". Sie muss dort trotzdem auf "Aus" gesetzt werden.
Wie können Werte an ein Sub-Template übergeben werden?
Schritt 1
Im Sub-Template muss definiert
werden, welche Werte übergeben werden können. Hierzu
müssen entsprechende übergabeparameter angelegt
werden:
<?param:Parametername; string('Standardwert')?>
Der Standardwert kommt nur zum Tragen, wenn ein Parameter beim Aufruf des Sub-Templates nicht gesetzt wurde. Die Definition des Sub-Templates erweitert sich dann wie folgt:
<?template:Sub-Template-Name?>
<?param:Parametername1; string('Standardwert1')?>
eventuell weitere Parameter
Inhalt des Sub-Templates
<?end template?>
Hinweis: Damit das gewünschte Layout erzielt wird, kann es erforderlich sein, innerhalb der Sub-Template-Definition alle Zeilenumbrüche vor dem eigentlichen Ausgabeinhalt zu entfernen.
<?template:Sub-Template-Name?><?param:Parametername1; string('Standardwert1')?>eventuell weitere ....
Im Inhaltsbereich des Sub-Templates können die Parameterwerte dann nach Belieben eingebunden werden:
<?$Parametername?> z.B. gibt den entsprechenden Wert direkt aus.
Schritt 2
Beim Aufruf des Sub-Templates
können die Parameter mit Werten belegt werden.
Fester Wert:
<?with-param:Parametername;string(’Parameterwert’)?>
Wert eines Datenelements:
<?with-param:Parametername;DATENELEMENTNAME/XPath-Ausdruck?>
Der Aufruf des Sub-Templates sieht dann z.B. so aus:
<?call:Sub-Template-Name?>
<?with-param:Parametername1;string('ein fester Wert')?>
<?with-param:Parametername2;DATENELEMENT_XY?>
<?end call?>
Hinweis: Bei
der Verwendung innerhalb von
<?for-each:…?>-Bereichen kann folgender Fehler
auftreten:
XML-22047: (Error) Invalid instantiation of
'xsl:with-param' in 'xsl:for-each' context.
Erweitern Sie in diesem Fall den Aufruf folgendermaßen:
<?call@inlines:Sub-Template-Name?>
Kann ein Sub-Template ohne Verwendung von übergabeparametern auch direkt auf die Daten zugreifen?
Aus dem Sub-Template heraus kann grundsätzlich ganz normal per X-Path auf die Berichtsdaten zugegriffen werden. Dabei können aber je nach Anwendungsfall sehr schnell Fehler auftreten, z.B. weil
* die XML-Struktur der Datengrundlage von Bericht zu Bericht unterschiedlich ist => andere Datenelementnamen, Hierarchien
* der Kontext der Aufrufer unterschiedlich ist, z.B.
*** CALL in Bericht 1 innerhalb eines FOR-EACH
*** CALL in Bericht 2 auf Root-Ebene
Wie lässt sich die Pfadangabe für das Einbinden der Sub-Template-Datei parametrisieren?
Voraussetzung:
Installation eines der neueren Patch-Sets von Oracle Support
für 10.1.3.4.0 oder 10.1.3.4.1 (getestet mit 10.1.3.4.1
Patch-Release vom Juni 2010).
Beispiel
<?import:${PROTOKOLL}:${PFAD}/subtemplate.rtf?>
* Parameter PROTOKOLL setzt die Zugriffsart (http, file)
* Parameter PFAD setzt den Speicherort, mit führendem // (für http) oder /// (für file)
Aktuell vorhandene Einschränkungen
* Es ist nicht möglich, Protokoll und Pfadangabe über einen einzigen Parameter zu setzen, dies würde zu einer Fehlermeldung führen.
* Es ist nicht möglich, den kompletten Dateinamen über den Pfadparameter zu setzen, da ein Fehler auftritt, wenn die Pfadangabe nicht mit mindestens einem Zeichen außerhalb des Parameters abgeschlossen wird.
Für die Definition der verwendeten Parameter gibt es mehrere Möglichkeiten:
BI Publisher Server-Frontend
Die Parameter können direkt im Bericht gesetzt werden, z.B. als ausgeblendete Parameter.
BI Publisher Konfigurationsdatei xdo.cfg
Beispiel:<config version="1.0.0" xmlns="http://xmlns.oracle.com/oxp/config/">
<properties>
<property name="xslt.PROTOKOLL">"file"</property>
<property name="xslt.PFAD">"///C:\bip"</property>
</properties>
</config>
Das Präfix xslt.
ist hier zwingend erforderlich, wird im
<?import?>-Ausdruck im RTF-Template aber nicht mit
angegeben.
Speicherorte:
Für Template Builder for Word z.B.: C:\Programme\Oracle\BI Publisher\BI Publisher Desktop\Template Builder for Word\config
BI Publisher Server: im Berichts-Repository z.B.: /home/oracle/XMLP/Reports/<Pfad des Berichts> (Gilt nur für den einen Bericht)
BI Publisher Server: in der Java-Installation unter /jre/lib, z.B.: /usr/java/jdk1.6.0/jre/lib (Gilt für alle Berichte)