Difference between revisions of "Html-Templates"

From Limbas Wiki

Jump to: navigation, search
(Template-Gruppen)
Line 37: Line 37:
  
 
Nach der Öffnungsklammer bzw. als "target"-Attribut kann optional ein Medium (form/report) angegeben werden, für welchen das Element angezeigt werden soll. Ist kein Medium angegeben wird es für alle Medien angezeigt.  
 
Nach der Öffnungsklammer bzw. als "target"-Attribut kann optional ein Medium (form/report) angegeben werden, für welchen das Element angezeigt werden soll. Ist kein Medium angegeben wird es für alle Medien angezeigt.  
 
==Unter-Template-Element==
 
<code>${''Einleitung''}</code> bzw.
 
 
<code><lmb type="template" name="Einleitung" /></code>
 
 
Anstelle dieses Platzhalters wird beispielsweise die Berichtsvorlage mit dem Namen ''Einleitung'' eingefügt. Der Name einer Berichtsvorlage muss eindeutig sein. Die Berichtsvorlagen-Tabelle kann aber auch so gefiltert werden (bspw. nach Sprache des angemeldeten Nutzers), dass der Name bei der Auswertung eindeutig ist.
 
  
 
==Dateninhalt==
 
==Dateninhalt==
Line 92: Line 85:
  
 
Des Weiteren kann statt der Daten auch die Beschreibung bzw. der Titel des Feldes angezeigt werden (Siehe [[Tabellen#Tabellenfeld-Einstellungen|Tabellenfeld-Einstellungen]]).
 
Des Weiteren kann statt der Daten auch die Beschreibung bzw. der Titel des Feldes angezeigt werden (Siehe [[Tabellen#Tabellenfeld-Einstellungen|Tabellenfeld-Einstellungen]]).
 +
 +
==Unter-Element==
 +
<code>${''Einleitung''}</code> bzw.
 +
 +
<code><lmb type="template" name="Einleitung" /></code>
 +
 +
Anstelle dieses Platzhalters wird beispielsweise die Berichtsvorlage mit dem Namen ''Einleitung'' eingefügt. Der Name einer Berichtsvorlage muss eindeutig sein. Die Berichtsvorlagen-Tabelle kann aber auch so gefiltert werden (bspw. nach Sprache des angemeldeten Nutzers), dass der Name bei der Auswertung eindeutig ist.
 +
 +
==Template-Gruppen==
 +
Oft teilt ein großer Teil der Briefe das gleiche Layout und nur ein kleiner Teil wird ausgetauscht, z.B. Text-Inhalt oder wessen Unterschrift unten im Brief platziert wird. Für jeden unterschiedlichen Brief müsste ein eigener Limbas-Bericht erstellt werden.
 +
 +
 +
<code><nowiki>${{</nowiki>''GruppenName''}}</code> bzw.
 +
 +
<code><lmb type="group" name="GruppenName" /></code>
 +
 +
Template-Gruppen vereinfachen dieses Szenario. Es wird nur ein (Grund-)Bericht angelegt, in welchem ein Template-Gruppen-Tag (doppelte geschweifte Klammern, siehe oben) vorkommt. Dieses Tag steht für einen von mehreren Datensätzen der Template-Tabelle (also Text/Html) die zu der angegebenen Gruppe zugewiesen wurden. Soll der Bericht gedruckt werden, wird das Gruppen-Tag erkannt und der Nutzer kann den gewünschten Datensatz der Gruppe auswählen.
 +
Ein Datensatz einer Gruppe kann dabei auch selbst wieder Gruppen-Tags enthalten.
 +
 +
 +
<code><nowiki>${{</nowiki>''GruppenName''[desc=''Beschreibung''][id=''eindeutige_id'']}}</code> bzw.
 +
 +
<code><lmb type="group" name="GruppenName" title="Beschreibung" id="eindeutige_id" /></code>
 +
 +
Hinter dem Gruppennamen kann eine leserliche Beschreibung des Gruppen-Tags angefügt werden. Diese wird anstelle des Gruppennamens im Druck-Menü angezeigt.
 +
Kommen in einem Bericht mehrere Tags der selben Gruppe vor, muss eine eindeutige ID pro Tag vergeben werden um eine korrekte Auflösung der Gruppen zu gewährleisten.
  
 
==Funktionsaufruf==
 
==Funktionsaufruf==
Line 139: Line 158:
  
 
Wertet die Funktion ''report_FunktionsName''/''form_FunktionsName'' bzw. das Feld ''EinDatenFeld'' aus. Evaluiert der Wert zu ''true'', wird der Teil zwischen if und endif im Bericht ausgegeben, andernfalls nicht. Zwischen beiden werden auch <code>${elseif ...}</code> und <code>${else}</code> unterstützt.
 
Wertet die Funktion ''report_FunktionsName''/''form_FunktionsName'' bzw. das Feld ''EinDatenFeld'' aus. Evaluiert der Wert zu ''true'', wird der Teil zwischen if und endif im Bericht ausgegeben, andernfalls nicht. Zwischen beiden werden auch <code>${elseif ...}</code> und <code>${else}</code> unterstützt.
 
==Template-Gruppen==
 
Oft teilt ein großer Teil der Briefe das gleiche Layout und nur ein kleiner Teil wird ausgetauscht, z.B. Text-Inhalt oder wessen Unterschrift unten im Brief platziert wird. Für jeden unterschiedlichen Brief müsste ein eigener Limbas-Bericht erstellt werden.
 
 
 
<code><nowiki>${{</nowiki>''GruppenName''}}</code> bzw.
 
 
<code><lmb type="group" name="GruppenName" /></code>
 
 
Template-Gruppen vereinfachen dieses Szenario. Es wird nur ein (Grund-)Bericht angelegt, in welchem ein Template-Gruppen-Tag (doppelte geschweifte Klammern, siehe oben) vorkommt. Dieses Tag steht für einen von mehreren Datensätzen der Template-Tabelle (also Text/Html) die zu der angegebenen Gruppe zugewiesen wurden. Soll der Bericht gedruckt werden, wird das Gruppen-Tag erkannt und der Nutzer kann den gewünschten Datensatz der Gruppe auswählen.
 
Ein Datensatz einer Gruppe kann dabei auch selbst wieder Gruppen-Tags enthalten.
 
 
 
<code><nowiki>${{</nowiki>''GruppenName''[desc=''Beschreibung''][id=''eindeutige_id'']}}</code> bzw.
 
 
<code><lmb type="group" name="GruppenName" title="Beschreibung" id="eindeutige_id" /></code>
 
 
Hinter dem Gruppennamen kann eine leserliche Beschreibung des Gruppen-Tags angefügt werden. Diese wird anstelle des Gruppennamens im Druck-Menü angezeigt.
 
Kommen in einem Bericht mehrere Tags der selben Gruppe vor, muss eine eindeutige ID pro Tag vergeben werden um eine korrekte Auflösung der Gruppen zu gewährleisten.
 
  
 
=Beispiel=
 
=Beispiel=

Revision as of 14:41, 12 January 2021

Admin-Dokumentation / Hauptseite



Einleitung

Die Limbas Formular-/Bericht-Editoren sind eine gute Möglichkeit, Formulare oder Berichte per Drag&Drop pixel-genau zu entwerfen. Einzelne Elemente wie bspw. Fließtext oder Dateninhalte sind dabei jedoch voneinander getrennt und ließen sich bisher nur vom Administrator mit Php-Skripten miteinander kombinieren.

Für Newsletter, Anschreiben, Rechnungen etc. ist es jedoch oft notwendig, Dateninhalte wie Kunden-Namen oder Preise direkt in den Fließtext zu integrieren. Seit Version 3.6 ist dies durch die neue Html-Template-Engine in Limbas komfortabel und nutzerfreundlich mit dem Wysiwyg-Editor möglich.

Funktionsweise

In das neue Template-Element im Formular-/Berichts-Editor kann normaler Text geschrieben werden, aber auch direkt Html. Die Besonderheit im Vergleich zum Textblock-Element ist, dass das Template-Element verschiedene Platzhalter im Text erkennt, welche von der Template-Engine für den Nutzer automatisch ersetzt werden. So können beispielsweise Dateninhalte eingebunden werden.

Oft werden manche Texte, wie bspw. Firmendaten, in mehreren Berichten benutzt und sollen nicht in jedem Bericht erneut eingegeben werden. Die Template-Engine erlaubt dafür einen modularen Aufbau der Formulare/Berichte: Textbausteine können in einer eigenen Tabelle des Typs Berichtsvorlagen definiert werden und mit einem Unter-Template-Element-Platzhalter in andere Template-Elemente eingebunden werden. Die Tabelle muss beim Erstellen des Template-Elements ausgewählt werden.

Platzhalter-Syntax

Es gibt zwei Möglichkeiten, Platzhalter einzufügen: Entweder mit der ${...}-Syntax oder als ein <lmb /> Html-Element. In den folgenden Beispielen werden immer beide (äquivalenten) Varianten gezeigt.

${Einleitung} bzw.

<lmb type="template" name="Einleitung" /> (wird immer angezeigt)


${form: Einleitung} bzw.

<lmb type="template" name="Einleitung" target="form" /> (wird nur im Formular angezeigt)


${report: Einleitung} bzw.

<lmb type="template" name="Einleitung" target="report" /> (wird nur im Bericht angezeigt)

Nach der Öffnungsklammer bzw. als "target"-Attribut kann optional ein Medium (form/report) angegeben werden, für welchen das Element angezeigt werden soll. Ist kein Medium angegeben wird es für alle Medien angezeigt.

Dateninhalt

${->Name} bzw.

<lmb type="data" src="->Name" />

Erkennbar an dem Pfeil (->). Hier wird beispielsweise der Inhalt des Feldes Name eingefügt. Die Daten kommen dabei aus dem Datensatz, für den das Formular geöffnet bzw. für den der Bericht gedruckt wird.


${=>Auftraege->Name} bzw.

<lmb type="data" src="=>Auftraege->Name" />

Die Tabelle ist dabei implizit durch den Datensatz angegeben, man kann sie für mehr Übersichtlichkeit aber auch explizit mit dem Doppelpfeil (=>) angeben. Um Felder einer 1:1-verknüpften Tabelle abzufragen kann die gleiche Syntax verwendet werden.


${->Kunde->Name} bzw.

<lmb type="data" src="->Kunde->Name" />

Es werden auch Verknüpfungsfelder unterstützt. Das obere Beispiel zeigt beispielsweise den Namen des verknüpften Kunden an. Kunde ist hierbei der Name des Verknüpfungsfeldes der aktuellen Tabelle.


${->Kunde->Name|"Kein Kunde verknüpft!"} bzw.

<lmb type="data" src="->Kunde->Name" alt="Kein Kunde verknüpft!" />

Es kann auch ein Defaultwert angegeben werden für den Fall, dass im Datensatz für das Feld kein Wert eingetragen ist.


${->Name[key=value]} ${->Name[flag]} bzw.

<lmb type="data" src="->Name" data-key="value" /> <lmb type="data" src="->Name" data-flag />

In eckigen Klammern können weitere Optionen übergeben werden. Diese werden je nach Medium (Formular / Bericht) unterschiedlich unterstützt/gehandhabt.


${->Name} // => "Alfred"

${->Name[show=description]} // => "Vorname"

${->Name[show=title]} // => "Vorname des Kunden" bzw.

<lmb type="data" src="->Name" data-show="description" /> // => "Vorname" etc.

Des Weiteren kann statt der Daten auch die Beschreibung bzw. der Titel des Feldes angezeigt werden (Siehe Tabellenfeld-Einstellungen).

Unter-Element

${Einleitung} bzw.

<lmb type="template" name="Einleitung" />

Anstelle dieses Platzhalters wird beispielsweise die Berichtsvorlage mit dem Namen Einleitung eingefügt. Der Name einer Berichtsvorlage muss eindeutig sein. Die Berichtsvorlagen-Tabelle kann aber auch so gefiltert werden (bspw. nach Sprache des angemeldeten Nutzers), dass der Name bei der Auswertung eindeutig ist.

Template-Gruppen

Oft teilt ein großer Teil der Briefe das gleiche Layout und nur ein kleiner Teil wird ausgetauscht, z.B. Text-Inhalt oder wessen Unterschrift unten im Brief platziert wird. Für jeden unterschiedlichen Brief müsste ein eigener Limbas-Bericht erstellt werden.


${{GruppenName}} bzw.

<lmb type="group" name="GruppenName" />

Template-Gruppen vereinfachen dieses Szenario. Es wird nur ein (Grund-)Bericht angelegt, in welchem ein Template-Gruppen-Tag (doppelte geschweifte Klammern, siehe oben) vorkommt. Dieses Tag steht für einen von mehreren Datensätzen der Template-Tabelle (also Text/Html) die zu der angegebenen Gruppe zugewiesen wurden. Soll der Bericht gedruckt werden, wird das Gruppen-Tag erkannt und der Nutzer kann den gewünschten Datensatz der Gruppe auswählen. Ein Datensatz einer Gruppe kann dabei auch selbst wieder Gruppen-Tags enthalten.


${{GruppenName[desc=Beschreibung][id=eindeutige_id]}} bzw.

<lmb type="group" name="GruppenName" title="Beschreibung" id="eindeutige_id" />

Hinter dem Gruppennamen kann eine leserliche Beschreibung des Gruppen-Tags angefügt werden. Diese wird anstelle des Gruppennamens im Druck-Menü angezeigt. Kommen in einem Bericht mehrere Tags der selben Gruppe vor, muss eine eindeutige ID pro Tag vergeben werden um eine korrekte Auflösung der Gruppen zu gewährleisten.

Funktionsaufruf

${=FunktionsName()} bzw.

<lmb type="func" name="FunktionsName" />

Erkennbar an dem Gleichheitszeichen (=). Der Server wertet bei Berichten die Funktion report_FunktionsName aus, bei Formularen die Funktion form_FunktionsName. Diese kann in den Skript-Erweiterungen implementiert sein. Das report_-/form_-Präfix sorgt dafür, dass keine Systemfunktionen direkt aufgerufen werden können.

An die Funktion können beliebig viele Parameter übergeben werden (getrennt durch Komma). Die Anzahl der übergebenen Parameter sollte dabei mit der Anzahl der Parameter der implementierten Funktion übereinstimmen um Fehler zu vermeiden. Es gibt dabei 4 Typen von Parametern:

Texte
${=FunktionsName("Ein beliebiger String")} bzw.
<lmb type="func" name="FunktionsName"><lmb type="value" value="Ein beliebiger String" /></lmb>
Zahlen
${=FunktionsName(-42.5)} bzw.
<lmb type="func" name="FunktionsName"><lmb type="value" value="-42.5" /></lmb>
Dateninhalte (Pfeil ->)
${=FunktionsName(->Kunde->Name)} bzw.
<lmb type="func" name="FunktionsName"><lmb type="data" src="->Kunde->Name" /></lmb>
Funktionsaufruf (Gleichheitszeichen =)
${=FunktionsName(=AndererFunktionsName())}
<lmb type="func" name="FunktionsName"><lmb type="func" name="AndererFunktionsName" /></lmb>
Die innere Funktion kann dabei wieder die gleichen Typen von Parametern haben

Das Ergebnis der Funktion sollte gültiges Html sein, das an der Stelle eingefügt wird. Gibt die Funktion stattdessen ein Objekt der Klasse TemplateElement (extra/template/base/TemplateElement.php) zurück, wird dieses an der Stelle eingebunden.

If/Else/Endif

${if =FunktionsName()}...${endif} bzw.

<lmb type="if"><lmb condition="func" name="FunktionsName" /></lmb> ... <lmb type="endif" />


${if ->EinDatenFeld}...${endif} bzw.

<lmb type="if"><lmb condition="data" src="EinDatenFeld" /></lmb>...<lmb type="endif" />


${if =FunktionsName()}...${elseif ->EinDatenFeld}...${else}...${endif} bzw.

<lmb type="if"><lmb condition="func" name="FunktionsName" /></lmb>
... 
<lmb type="elseif"><lmb condition="data" src="->EinDatenFeld" /></lmb>
...
<lmb type="else" />
...
<lmb type="endif" />

Wertet die Funktion report_FunktionsName/form_FunktionsName bzw. das Feld EinDatenFeld aus. Evaluiert der Wert zu true, wird der Teil zwischen if und endif im Bericht ausgegeben, andernfalls nicht. Zwischen beiden werden auch ${elseif ...} und ${else} unterstützt.

Beispiel

Example:

Es wird ein Bericht für die Tabelle Kontakte erstellt. In das Berichts-Element im Editor wird folgender Text eingetragen:

${Rechnung}

Dies bewirkt, dass in dem Bericht der Inhalt des Datensatzes mit Namen Rechnung aus der Berichtsvorlagen-Tabelle eingefügt wird. In diesem ist der Inhalt definiert:

${PersonenDaten}
Rechnung Text Blabla

In dem Datensatz mit Namen PersonenDaten:

${->Anrede} ${->Vorname} ${->Nachname}, geb. ${=formatDate(->GeburtsDatum,"d.m.Y")}

Es werden hier Anrede/Vorname/Nachname aus der Tabelle Kontakte von dem Datensatz genommen, für den der Bericht gedruckt wird. An die Funktion wird als erster Parameter das Geburtsdatum des Kontakts übergeben (aus der Datenbank). Als zweiter Parameter wird direkt der String d.m.Y übergeben. So kann die Funktion für weitere Datumsformate wiederverwendet werden. Sie kann beispielsweise so in einer Erweiterung (ext_report.inc) implementiert sein:

function report_formatDate($date, $format) {
    $stamp = strtotime($date);
    return date($format, $stamp);
}

So hat der Bericht eine klare Struktur, kann direkt mit Html designed werden und die Personendaten können in weiteren Berichten wiederverwendet werden.