Vorausfüllen von Dropdown-Listen in dynamischen PDF-Formularen aus einer Backend-Datenquelle mit LiveCycle ES2.5

Grundkenntnisse in LiveCycle Designer ES2 und einer Datenbank Ihrer Wahl (im Mittelpunkt dieser Anleitung steht MySQL).

MySQL-Datenbank
Ein Texteditor wie Notepad++

Fortgeschr.

Einer der Hauptvorteile elektronischer Formulare ist ihre Dynamik. Ein Formular muss nicht mit einem Datensatz erstellt und dann auf unbestimmte Zeit so belassen werden. Ein elektronisches Formular, das mit einer Backend-Datenquelle verknüpft wurde, kann jederzeit dynamisch aktualisiert werden. Ein häufiger Einsatz dieses Konzepts ist die Verwendung einer Dropdown-Liste in einer dynamischen PDF-Vorausfüllung mit Daten aus einer Datenbank.

Zur Veranschaulichung des Prozesses wollen wir eine einfache Tabelle in einer MySql-Datenbank erstellen. Anschließend fügen wir der Datenbanktabelle drei Zeilen hinzu und erstellen in Designer ein einfaches PDF-Formular mit einer Dropdown-Liste, die automatisch von dieser Datenquelle vorausgefüllt wird.

In dieser Anleitung wird die Verwendung einer MySql-Datenbank als Backend-Datenquelle beschrieben. Die allgemeinen Grundsätze für die Bindung dieser Datenquelle an das Formular sind jedoch die gleichen, unabhängig davon, welche Backend-LiveCycle-kompatible Datenbank Sie verwenden. In dieser Anleitung wird auch davon ausgegangen, dass Sie mit dem Erstellen und Bearbeiten von Tabellen in MySql vertraut sind. Diese Themen werden nicht ausführlich behandelt, da der Hauptschwerpunkt dieser Anleitung darin besteht, die Datenquellen an das Dropdown-Listen-Formularobjekt zu binden.

Der erste Schritt besteht darin, eine Tabelle in Ihrer Datenbank zu erstellen. In dieser Tabelle werden die Werte gespeichert, die letztendlich im Dropdown-Listenobjekt angezeigt werden:

Der nächste Schritt besteht darin, ein XSD-Schema-Dokument zu erstellen. Dafür gibt es Möglichkeiten:  Bei beiden Optionen besteht der erste Schritt darin, in Ihrer LiveCycle-Projekthierarchie in Workbench einen Ordner namens „Schema“ anzulegen. Nachdem der Ordner angelegt wurde, führen Sie einen der folgenden Schritte aus, um ein Schema zu erstellen:

• Option 1: Klicken Sie mit der rechten Maustaste auf den neu erstellten Ordner „Schema“, und wählen Sie die Erstellung einer neuen XML-Schema-Datei aus.  Workbench öffnet den verknüpften Standard-Texteditor, und die neue Datei (eine Textdatei) verfügt über die entsprechende DocType-Deklaration und die Basisschema-Tag-Struktur für ein XML-Schema. Sie können dann den Editor verwenden, um den restlichen Schema-Code zu schreiben, um dann das Schemadokument zu speichern (wobei Sie darauf achten müssen, die Dateierweiterung „.xsd“ zu verwenden).
• Option 2: Erstellen Sie das Schemadokument mit einem Drittanbieter-Editor wie Notepad++. Der Vorteil eines Editors wie Notepad++ liegt darin, dass der Editor mit Farben die Kodierung erleichtert, sobald Sie die XML-DocType-Benennung oben im Textdokument einfügen. Sobald die Datei erstellt wurde, benennen Sie das Schema entsprechend. Achten Sie darauf, dass Sie das Schema mit der Dateierweiterung „.xsd“ abspeichern. An dieser Stelle müssen Sie die XSD-Datei (von dem Ort, an dem Sie sie nach der Bearbeitung gespeichert haben) in Ihren Schemaordner ziehen und das Dokument dort ablegen.

In beiden Fällen müssen Sie ein einfaches Schemadokument erstellen, wie im folgenden Schema dargestellt. 

Beachten Sie, dass sich die Elemente firstName und lastName zwar im abgebildeten Schema befinden, diese jedoch nicht für das Ausfüllen der Dropdown-Liste erforderlich sind. Der wichtige Teil des Schema-Codes für diese Anleitung ist das testerList-Element. 

Beachten Sie auch, dass es sich bei diesem Element um einen complexType handelt, der eine Folge von „Tester“-Unterelementen hat; dieser „Tester“-Typ wiederum ist ebenfalls ein complexType, der eine Reihe von Werten enthält, die die ID und den Namen der Objekte enthalten, die schließlich in der Dropdown-Liste erscheinen werden.

Aus Gründen der Schnelligkeit wird in dieser Anleitung davon ausgegangen, dass der Leser ein neues Formular mit Designer aus Workbench oder direkt in Designer erstellen kann. Erstellen Sie an diesem Punkt des Prozesses ein neues Formular (oder öffnen Sie das vorhandene Formular, an das Sie die Backend-Daten binden möchten) und öffnen Sie das Formular zur Bearbeitung im Designer. 

Nachdem das gewünschte Formular geöffnet wurde, klicken Sie auf die Registerkarte „Datenansicht“. Standardmäßig befindet sich diese Registerkarte auf der linken Seite der Designer-IDE, zwei Registerkarten über der Registerkarte „Hierarchie“.

Klicken Sie mit der rechten Maustaste auf den Weißraum der Registerkarte „Datenansicht“ und klicken Sie auf „Neue Datenverbindung“. 

Benennen Sie in dem sich öffnenden Fenster (Abbildung 1) Ihre neue Verbindung entsprechend (wobei die Benennung dieses Objekts je nach Aufgabenstellung willkürlich ist), wählen Sie die Optionsschaltfläche „XML-Schema“ und drücken Sie auf die Schaltfläche „Weiter“.

Zeigen Sie dann einfach auf den Speicherort des Schemadokuments. Wenn Sie die Schritte direkt in dieser Anleitung ausführen, dann ist dieser Speicherort der Ordner „Schema“ in Ihrer Workbench-Hierarchie (Abbildung 2).

Wenn Sie das neue Formular mit Designer aus Workbench erstellen möchten, können Sie auch das Formulardatenmodell angeben, das Ihnen den Verweis auf dieses Schema ermöglicht (Abbildung 3).

Übernehmen Sie im Assistenten die Standardeinstellungen für die übrigen Ansichten.

Erstellen Sie eine Dropdown-Liste, indem Sie das Dropdown-Listenobjekt aus der Palette „Objektbibliothek“ in den Formularkörper ziehen bzw. dort ablegen (Abbildung 4).

Nachdem das Dropdown-Objekt auf das Formular gezogen wurde, klicken Sie auf das Menü „Extras“, das sich oben in der Designer-IDE befindet. Wählen Sie in diesem Tools-Menü „Optionen“. Navigieren Sie im erscheinenden Popup-Fenster „Optionen“ zur Auswahl „Datenbindung“ im Menü auf der linken Seite. Überprüfen Sie, ob die Option „Dynamische Eigenschaften anzeigen“ aktiviert ist, und klicken Sie dann auf die Schaltfläche „OK“ (Abbildung 5).

Navigieren Sie zurück zur Dropdown-Liste im Hauptteil des Formulars, und klicken Sie darauf. In der Palette „Objekt“ der Dropdown-Liste (standardmäßig rechts unten in der Designer-IDE zwei Registerkarten über „Layout“) navigieren Sie zur Unterregisterkarte „Feld“ (Abbildung 6).  

Klicken Sie in der Mitte dieser Registerkarte auf das grüne Link-Objekt „ListItems:“.

Klicken Sie in der Zeile „Elemente“ auf das Objekt „Navigation“ rechts neben dem Eingabefeld „Elemente“.  Navigieren Sie zur Hierarchieebene „Tester“. Das Dateneingabefeld sollte mit dem den folgenden Wert befüllt werden: $record.testerList.Tester[*]

Beachten Sie die hier verwendete [*]-Konvention, die immer dann verwendet wird, wenn ein Schema mehrmals wiederholt wird. Erinnern Sie sich daran, dass wir im Schema ein Segment hatten, das wie folgt aussah (Abbildung 7):

Wenn wir dieses Schema an das Dropdown-Listenobjekt binden, wird es auf der Ebene „Tester“ der Schemahierarchie gebunden. Beachten Sie auch, dass für dieses Element der Attribut „maxOccurs“ auf „unbounded“ gesetzt ist. Dieser Attributwert muss im Schema festgelegt werden, damit die „[*]“-Konvention in LiveCycle funktioniert.

Beachten Sie schließlich, dass es im Schema nur zwei Elementwerte gibt: einen für „Name“ und einen für „ID“. Diese Elemente sind an den Abschnitt „testUsers“ der Datenbank gebunden, der wie folgt aussieht: testUsers-Werte (100, ‚Jim Jones‘, 0). Denken Sie daran, dass es drei testUsers in der Datenbank (Jim, Sally und Fred) gab, doch hier haben wir nur ein „Tester“-Element, das die Elemente ID und Name enthält. Diese Elemente entsprechen den Datenbankwerten 100 (ID) und Jim Jones (Name) (wir zeigen Ihnen im folgenden Abschnitt, wie das Schema mit der Datenbank verbunden ist). Merken Sie sich einfach, dass die „[*]“-Konvention, wenn sie an das maxOccurs= „unbounded“ Element im Schema gebunden ist, durch die Datenbanktabelle iteriert und „für jedes“ Element, über das sie in der Tabelle iteriert, diesen Wert erfasst, ihn an die Datenstandards anpasst, die die XSD definiert, und dann unter Verwendung des an das Formular gebundenen Schemas das Dropdown-Listenfeld entsprechend ausfüllt.

Es bleiben noch einige weitere Schritte, um das Bindungsverfahren abzuschließen. Als nächstes klicken Sie auf die Registerkarte „Bindung“ unter der Palette „Objekt“.  Klicken Sie neben dem Eingabefeld „Datenbindung“ erneut auf das Navigationssymbol rechts. Bewegen Sie den Mauszeiger über das Element „Datenverbindung verwenden“ (Abbildung 8). An der Seite wird ein Popup mit den Werten aus den Elementen im Schema angezeigt. 

Wenn der Benutzer ein Element in der Dropdown-Liste auswählt, wird die ausgewählte ID im Element „selectedTester“ gespeichert. Klicken Sie dann in der Liste auf diesen Namen.

Wählen Sie im angezeigten Popup „Bindungseigenschaften“ (Abbildung 9), welche Eigenschaften Sie im Dropdown-Element „Liste“ aktualisieren möchten.  In den meisten Fällen kann man sich dafür entscheiden, keine Eigenschaften zu aktualisieren oder, wie wir uns hier entschieden haben, das Feld „Name“ des LiveCycle-Formularobjekts zu aktualisieren (dies geschieht einfach aus Gründen der Konsistenz zwischen den Namen der Formularobjekte und den Namen der Schemaelemente). 

Zum größten Teil lassen wir LiveCycle die Beschriftungs- und Typinformationen verarbeiten. Wenn Sie diese Kontrollkästchen aktiviert lassen, würden die Daten im LiveCycle-Formular überschrieben. Wenn Sie beispielsweise ein „Datum“-Feld vom Typ „Datum“ einem Schemaelement zuordnen, bei dem das „Datum“-Element in eine „xs:string“ gecastet wurde, und die Option „Typ“ in diesem Dialogfeld aktiviert lassen, würden die Typinformationen des „Datum“-Objekts, das als String ausgegeben werden soll, überschrieben. Schemaelemente werden häufig als „xs:string“-Werte hinterlegt, damit das Schema bei der Typisierung etwas nachvollziehbarer wird, und die Strukturierung der Daten bleibt in Designer den integrierten Tools für die Dateneingabe und -überprüfung überlassen.

Speichern Sie an dieser Stelle das Formular und schließen Sie Designer.

Jetzt erstellen wir einen Hauptprozess in Workbench und dann einen Vor-Rendering-Prozess, in dem wir unsere Datenbanksuche ausführen. Auf diese Weise wird die Datenbank über das Schema mit dem Dropdown-Listenformularobjekt verbunden.

Klicken Sie in Workbench mit der rechten Maustaste auf den gewünschten Ort in Ihrer Hierarchie und erstellen Sie einen neuen Prozess (d. h. in einem Ordner „Prozesse“) mit dem Assistenten „Neuer Prozess“ (Abbildung 10). Nutzen Sie den Assistenten, um einen neuen Prozess zu erstellen und einen Startpunkt in Workspace anzulegen.

Übernehmen Sie für die restlichen Schritte im Assistenten die Standardeinstellungen.

Wählen Sie im Prozessdesigner den grünen „Startpunkt“ aus, und klicken Sie dann im Eigenschaftenfenster auf die Schaltfläche rechts neben dem Aktionsprofil (Abbildung 11):

Klicken Sie im angezeigten Dialogfeld auf die Schaltfläche neben „Datenprozess vorbereiten“, um das Dialogfeld „Neuen Datenprozess vorbereiten“ zu öffnen (Abbildung 12).

Übernehmen Sie die Standardwerte und klicken Sie zweimal auf die Schaltfläche „OK“, um die Dialogfelder zu verlassen und wieder ordnungsgemäß zu Workbench zu gelangen.

Fügen Sie im Prozess „NewForm1PrepareData“ eine JDBC-Aktivität (Java Database Connector) des Typs „Abfrage für mehrere Zeilen als XML“ hinzu. Die Datenquelle wird automatisch auf Ihre primäre Datenquelle eingestellt (Abbildung 13).

Klicken Sie auf die Schaltfläche „SQL-Anweisung“ und füllen Sie das Dialogfeld aus (Abbildung 14):

Um festzustellen, ob Sie die Verbindung erfolgreich hergestellt haben, drücken Sie die Taste „Test“. Nun sollten Ihnen die Ergebnisse ID und Name zurückgeben werden (wie oben abgebildet). Das weist auf eine funktionierende Abfrage hin.

Gehen Sie erneut zur Ansicht „Prozesserstellung“, klicken Sie auf das Objekt „JDBC“ und dann auf „XML-Informationen“ im rechten Bereich, um das unten abgebildete Dialogfeld anzuzeigen, das ausgefüllt werden sollte (Abbildung 15):

Sobald der obere Abschnitt dieses Dialogfelds abgeschlossen ist, drücken Sie die Schaltfläche „Test“, um die Verbindung zu überprüfen. Das gewünschte Ergebnis ist die XML, die im unteren weißen Feld dargestellt wird. Wie Sie sehen können, ordnen wir Datenbankspalten XML-Elementen zu, und in unserem Fall tragen wir dieselben Namen ein, auch wenn das nicht so sein muss.

Nachdem die Datenverbindung hergestellt und an das Schema gebunden wurde, müssen wir eine Variable erstellen, um die zurückgegebenen Daten einfacher handhaben zu können.  Klicken Sie dazu auf die Schaltfläche „Variable hinzufügen“ („+“) neben „Ausgabe“, und erstellen Sie eine neue Variable vom „Type: XML“. Geben Sie ihr den Namen „Tester“ (Abbildung 16). Diese Variable speichert nun die XML-Werte, die sich aus der Datenbankabfrage ergeben.

Erstellen Sie anschließend eine Aktivität zum Zuweisen von Werten, mit der die XML-Ausgabe unserer Abfrage in die XML-Variable „Tester“ verschoben wird, die wiederum zum Ausfüllen des Formulars genutzt wird.  Schließen Sie die „Wert zuweisen“-Aktivität an das JDBC-Objekt an (Abbildung 17).

Klicken Sie auf das Objekt „Aktivität“ und dann in dessen Eigenschaftenbereich auf das Bearbeitungssymbol „Stift“ im Bereich „Zuordnungen“, um das Bearbeitungsdialogfeld aufzurufen. Hier weisen wir die Variable „Tester“ an der richtigen Stelle in unserer Ausgabevariable zu (Abbildung 18):

Der Zielspeicherort lautet:

/process_data/xmlPrepareData/xdp/datasets/data/FormSchema/testerList

Speichern Sie jetzt den Prozess.

Jetzt können Sie die Anwendung bereitstellen. Wenn Sie dies in Workspace ausführen, sehen Sie die ausgefüllte Dropdown-Liste im Formular, etwa so (Abbildung 19):

Das bedeutet, Sie haben die Dropdown-Liste erfolgreich mit den Datenbankwerten gefüllt.

Wenn Sie zeigen möchten, dass die Variable „selectedTester“ mit der vom Benutzer gewünschten Auswahl aus der Dropdown-Liste eingestellt wurde, können Sie vorübergehend eine Texteingabe erstellen, indem Sie zum Designer zurückkehren und dieses Feld aus der Datenansicht in das Formular ziehen (Abbildung 20):

Speichern Sie das Formular ab, stellen Sie es bereit und führen Sie es erneut aus. Sie werden sehen, dass das Feld „selectedTester“ die ID des Benutzers wiedergibt, den Sie aus der Dropdown-Liste auswählen (Abbildung 21).

Der nächste Schritt könnte darin bestehen, die vom Benutzer eingegebenen oder ausgewählten Daten zu verwenden und sie in eine Datenbanktabelle einzufügen.

Die obige Anleitung veranschaulichte das Prinzip zur Erstellung einer Datenbanktabelle, die Bindung an ein Schema, die Bindung des Schemas an ein Formular und die Erstellung von XML-Variablen zur Speicherung der zurückgegebenen Daten.

Weitere Informationen zu ähnlichen Themen finden Sie unter Binden eines XML-Schema-Dokuments (XSD) an sich wiederholende Unterformularelemente mit Adobe LiveCycle Designer.