Das komplette PDF-Template oder nur einen Teil vervielfachen
Es ist möglich, das komplette PDF-Template oder nur einen ausgewählten Bereich innerhalb des PDF-Templates, für jeden ausgewählten Datensatz des Formulars, in bearbeiteter Kopie im fertigen PDF-Dokument zu erhalten.
Das komplette PDF-Template vervielfachen
Standardmäßig wird das PDF-Template für jeden ausgewählten Datensatz des Formulars einmal komplett abgearbeitet. Wenn Sie 10 Datensätze ausgewählt haben, dann wird das PDF-Template 10-mal kopiert und die Platzhalter in der Kopie mit den Daten des aktuellen Formular-Datensatzes ersetzt. Diese ersetzten finalen Texte werden, einer nach dem anderen, hinten an das PDF-Dokument angefügt.
Hinweis: Je nach Einstellung im PDF-Template auf dem Reiter "PDF Einstellungen", Parameter Einzelseite pro Datensatz, erfolgt das Anfügen eines fertig bearbeiteten PDF-Templates, pro gewähltem Datensatz des Formulars, mit oder ohne Seitenschaltung.
Nur einen Teil des PDF-Templates vervielfachen
Das gesamte PDF-Template für jeden ausgewählten Datensatz des Formulars einmal komplett zu Kopieren, ist nicht immer das gewünschte Verhalten. Manchmal wollen Sie etwa, dass innerhalb des PDF-Templates, für jeden Datensatz des Formulars, nur eine neue zusätzliche Tabellenzeile oder ein einzelner zusätzlicher Listeneintrag eingefügt wird.
Auch das ist möglich und dabei sogar sehr einfach umzusetzen. Sie müssen dazu nur das kleine class="loop" HTML-Attribut an der richtigen Stelle einfügen.
Sehen Sie sich dazu auch das Beispiel-Template “Bestellungen” im Demoformular “Obst” an. Sie müssen einfach nur das class="loop" HTML-Attribut in das HTML-Element schreiben, das multipliziert werden soll. Toggeln Sie den Editor auf die Ansicht “HTML-Code”, um das zu tun.
Bitte beachten Sie folgende kleine Einschränkung: Diese Loop-Elemente dürfen nicht geschachtelt werden.
Hinweis: Sie dürfen innerhalb eines HTML-Elements mit dem class="loop" Attribut kein weiteres HTML-Kind-Element mit einem class="loop" Attribut haben.
Sekundäre SQL-Statements
Ein ziemlich fortgeschrittenes Feature
Wir wollen Ihnen ein wirklich weitreichendes Tool zur Verfügung zu stellen. Das ist der Zweck der vielen möglichen SQL-Statements, die Sie auf dem Reiter “SQL-Statements” erstellt und im PDF-Template über den Namen referenzieren können.
Beliebige weitere Daten in das PDF-Dokument integrieren
Sie können damit zusätzlich zur primären Datensatzauswahl des Formulars, beliebige weitere Daten aus anderen Tabellen der Datenbank in das PDF-Dokument integrieren.
Diese sekundären Daten können stammen aus:
- zusätzliche Daten desselben Formulars,
- Daten eines anderen Formulars,
- beliebigen Daten aus der Joomla Datenbank.
Platzhalter im sekundären SQL-Statement beziehen sich auf den aktuellen primären Datensatz
Diese sekundären SQL-Statements ermöglichen eine zweite, möglicherweise abhänge Datenauswahl. Denn in den sekundären SQL-Statements können Sie sich durch Platzhalter auf die Felder des aktuellen primären Datensatzes beziehen (${item:field-name}). Details siehe weiter unten.
Die sekundären SQL-Statements werden sowohl angewandt, wenn Sie ein PDF-Dokument in der Administration erzeugen, als auch, wenn Sie es im Frontend erstellen.
Zwei Typen für sekundäre SQL-Statements
Prozesstyp “Form”
Wenn Sie weitere Daten desselben Formulars einschließen wollen, wählen Sie für das sekundäre SQL-Statement den Prozesstyp “Form”. Sie hinterlegen für den Prozesstyp “Form” ein SQL WHERE Teil-Statements. Diese SQL WHERE Teil-Statements beziehen sich allein auf den Teil eines kompletten SQL-Statements, der sich auf die Anfrage-Bedingungen hinter dem sogenannten ‘WHERE’ Schlüsselwort bezieht.
Prozesstyp “free”
Wenn Sie weitere beliebige Daten aus der Datenbank einschließen wollen, wählen Sie für das sekundäre SQL-Statement den Prozesstyp “free”. Sie hinterlegen für den Prozesstyp “free” ein ganz gewöhnliches vollständiges SQL-SELECT Statement.
Die 1:n Beziehung
Beide Prozesstypen von sekundären SQL-Statements (“Form” und “free”) werden für jeden Datensatz der Primärauswahl je ein mal angewandt. Die sekundären SQL-Statements können ihrerseits auch mehrere Datensätze zurückliefern.
Durch diese einfache Tatsache können Sie ein 1:n Beziehung von dem aktuellen Primär-Datensatz (1 Datensatz) zu den durch das sekundäre SQL-Statement selektierten Sekundär-Datensätzen (n Datensätze) erzeugen.
Sekundäre SQL-Statements an ein HTML-Element binden
Die Daten, die durch die sekundären SQL-Statements selektiert werden, können Sie in Ihrem PDF-Dokument verwenden. Sie müssen Sie das sekundäre SQL-Statement an die gewünschte Stelle im Dokument binden.
Platzieren Sie hierzu einfach folgende zwei Attribute in das gewünschte HTML-Element (etwa ein tr-Element):
- ein class="sql" Attribut zu Kennzeichnung des Wiederhol-Bereiches
- ein id="SQL statement name" Attribut zur Angabe des anzuwendenden sekundären SQL-Statements.
Platzhalter wie gewohnt auch für sekundäre SQL-Statements
Innerhalb des HTML-Elements fügen Sie dann wie gewohnt Platzhalter in der gewohnten Syntax ein. Die Platzhalter beziehen sich auf die Namen das verwendeten sekundären SQL-Statements, also auf das mit id="SQL statement name" ausgewählte sekundäre SQL-Statement. Sehen Sie hierzu auch weiter unten “Platzhalter für Daten aus SQL-Statements”.
Das geschachtelte HTML-Element wird vervielfacht
Angenommen Sie haben eine 1:n Beziehung zwischen der primären Datensatzauswahl und der sekundären Datensatzauswahl. Die Beziehung entsteht rein praktisch durch die Ausführung des sekundären SQL-Statements mit den aktuellen Daten des primären Datensatzes.
Nun wird das entsprechend gekennzeichnete oder auch gebundene HTML-Element, automatisch für jeden sekundären Datensatz kopiert:
- als Template verwendet,
- seine Parameter ersetzt und
- an den bestehende Text fortlaufend angehängt.
Die “HTML-Code” Ansicht des Editors verwenden
Am besten wechseln Sie im Editor mit dem Button “Toggle Editor” in die “HTML-Code” Ansicht um die Attribute einzufügen. Schauen Sie sich das “invoice” Beispiel PDF-Template des “register” Formulars hierzu genauer an. Beachten Sie insbesondere die Reiter “SQL Statements” und “Dokument” sowie die PDF-Vorschau.
Hinweis: Sie dürfen ein SQL-Statement nur 1 mal in Ihrem Dokument-Template einbinden.
Den jeweils letzten Datensatz merken wir uns
Während der Ersetzung der Platzhalter werden die Datenwerte, die gerade zum Ersetzen benutzt werden, automatisch als die “letzten Werte” gemerkt. Die letzten ersetzten Werte bleiben daher bis zum Ende der Dokumenterstellung vorhanden. Das gilt selbstverständlich pro verwendetem SQL-Statement.
Daher können Sie diese letzten Werte jederzeit an späterer Stelle im HTML-Template noch weiter verwenden. Also etwa auch ganz am Ende des PDF-Templates oder in den Bereichen von Seitenkopf und Seitenfuß.
Hinweis: Bitte beachten Sie, dass wirklich nur die letzten Daten des letzten Durchlaufs pro SQL-Statement gespeichert werden.
Interessant wird diese Wiederverwendung der gemerkten Daten vor allem bei SQL-Statements, die nur genau einen Datensatz liefern. Hier ist also der letzte Datensatz gleichzeit auch der einzige Datensatz. Seine Daten können überall und zu jeder Zeit und über das ganze PDF-Template verteilt, ersetzt werden.
Diese ‘einmaligen’ Datensätze mit nur einem Datensatz können sehr sinnvoll sein. Sie können dadurch beliebige notwendige Summen über alle nur denkbaren Dinge oder auch besondere einmalige Informationen aus der Datenbank direkt im HTML-Template verwenden.
Daten aus unterschiedlichen Formularen vereinen
Sie können SQL-Statements nutzen, um Daten, die mit unterschiedlichen Formularen übermittelt wurden, in einem PDF-Dokument zu vereinen.
Ein Beispiel
Sie haben ein erstes Formular, mit dem Sie allgemeine Benutzerdaten erheben. Und Sie haben ein zweites ein Formular, mit dem die Benutzer regelmäßig ihre Bestellungen abgeben.
Diese Daten könnten nun in einem einzigen PDF-Dokument vereint werden. Etwa um eine Übersicht aller Bestellungen eines Kunden mitsamt den hinterlegten Kundendaten zu erstellen.
Sehen Sie sich hierzu das “invoice” Beispiel PDF-Template des “register” Formulars für ein konkretes Beispiel genauer an. Beachten Sie insbesondere die Reiter “SQL Statements” und “Dokument” sowie die PDF-Vorschau.
Hinweis: Es ist nicht möglich sekundäre SQL-Statements zu schachteln. Ein HTML-Element mit class="sql" Attribute darf keine HTML-Kindelemente mit einem class="sql" Attribut haben. Auch keine HTML-Enkelelemente.
Platzhalter für Daten aus SQL-Statements
Das Format für Platzhalter ist das folgende: ${SQL-statement-name:SQL-field-name}.
Ein Beispiel
Sie haben ein SQL-Statement mit dem Namen “sum” auf dem “SQL-Statement” Reiter erstellt. Dieses Statement lautet:
select round(sum(F2179 * F2180), 2) as sum, round(sum(F2179 * F2180) * 0.19, 2) as tax from vf38_visforms_143 where id < 10;
Die Platzhalter zur Nutzung der Daten aus diesem Statement lauten: ${sum:sum} and ${sum:tax}.
Platzhalter in den SQL-Statements
SQL-Statements können auch selbst Platzhalter enthalten, die mit den aktuellen Werten ersetzt werden. Diese Ersetzung erfolgt immer unmittelbar bevor das SQL-Statement ausgeführt wird.
Diese Platzhalter können Werte referenzieren für:
- das Joomla Framework Objekt User
- ${user:parameter-name} und
- das Joomla Framework Objekt Input
- ${input:parameter-name}.
- Daten aus der primären Datenselektion, der gerade bearbeitet wird
- ${item:field-name}, etwa ${item:created_by}.
In den SQL-Statements zur Datenauswahl können Sie alternativ anstelle von
- der konkreten ID-Feldnamen F111 like ‘%value 1%‘
- auch Visforms Platzhalter ${maiden} like ‘%value 1%‘ verwenden.
Der “Testen” Button
Mit dem Button ‘Testen’ können Sie bereits vor der eigentlichen Generierung des PDF-Dokuments prüfen, ob das SQL-Statement zumindest fehlerfrei ist und wie viele Ergebnisse es liefert. Der Button ‘Testen’ kann allerdings nur verwendet werden, wenn noch kein Platzhalter im SQL-Statement enthalten sind. Die Platzhalter im SQL-Statement werden erst später zur Laufzeit ersetzt. Beim Klick auf den Button “Testen” wird also ein Platzhalter nicht ersetzt und verursacht dadurch einen SQL-Format-Fehler. Es erscheint eine entsprechende Fehler-Warnung.
Dieses SQL erzeugt keinen Fehler:
select name, username, email from #__users where id = 234;
Wobei der willkürliche Wert ‘234’ die ID eines existierenden Joomla-Benutzers ist.
Dieses SQL erzeugt einen Fehler:
select name, username, email from #__users where id = ${item:created_by};
Wir empfehlen daher das SQL-Statement zuerst mit festen Werten zu entwickeln. Erst gegen Ende fügen Sie, an den notwendigen Stellen, die gewünschten Platzhalter ein, wenn alles andere bereits korrekt funktioniert.
Bei etwas größeren und unhandlichen SQL-Statements empfehlen wir, die Entwicklung und den Test in einer explizit dafür vorgesehenen Umgebung vorzunehmen. Dazu gehören etwa der “MySQL Admin” oder eine dezidierte Entwicklungs-Umgebung (IDE). Auch in diesem Fall fügen Sie erst am Schluss, an den notwendigen Stellen, die gewünschten Platzhalter ein, wenn alles andere bereits korrekt funktioniert.