Fortgeschrittene PDF-Feature

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.

PDF SQL Statements

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.