Skripte
- Daniela Zimmermann
- Thomas Wepfer
- Robert Mühsig
- Dinah Bolli (Unlicensed)
- 1 Verschiedene Skript-Arten
- 2 Grundgerüst eines Skripts
- 3 Elemente innerhalb von CustomDataNodes und ihre Attribute
- 3.1 Line
- 3.2 Text
- 3.3 Element
- 3.4 Condition
- 3.4.1 Vergleichoperatoren
- 3.5 Snippet
- 3.6 List
- 3.7 Link
- 3.7.1 Bilder-Links
- 3.8 Image
Skripte dienen dem Anzeigen von Feldern aus verschiedenen Quellen (z. B. Profildaten oder Empfängerdialog). Mittels Bedingungen kann auch eine Logik eingebaut werden. Schlussendlich ist das Ziel von Skripten mehr Dynamik und Vereinfachung in den Vorlagen. Skripte, die in mehreren Vorlagen eingefügt werden sollen, werden in den Globalen Konfigurationen abgelegt. Von der Dokumentfunktion "Skripte" wird das Skript dann nur noch mit den Globalen Konfigurationen verknüpft.
Jedes Skript wird in das Start- und Endtag CustomDataNode eingeschlossen. Jedes CustomDataNode-Element benötigt das Attribut id, dessen Wert frei wählbar ist und eindeutig sein muss.
Um ein Text-Skript mit mehreren Zeilen zu erstellen, wird für eine Zeile mit dem Element Line gearbeitet. Mit dem Element Text wird ein fixer Text ausgegeben:
<CustomDataNode id="BeispielSkript">
<Line>
<Text>Erste Zeile</Text>
</Line>
<Line>
<Text>Zweite Zeile</Text>
</Line>
</CustomDataNode>Über Element werden Texte aus dem Profil oder aus externen Quellen angezogen. Damit beispielsweise Profildaten angezogen werden, wird die Identifikation des jeweiligen Feldes benötigt. Diese Feld-Id findet man im Dashboard unter "Fields" in der Spalte "FieldId":
Wurde die Feld-Id in das id-Attribut eingefügt, muss vor "User" immer noch "Profile." ergänzt werden (dies gilt nur für Profil-Felder, die angezogen werden möchten.). Sinn der Skripte ist es auch, die angezogenen Daten weiter zu verarbeiten oder mit Texten zu ergänzen. Im unteren Beispiel wurde als Ergänzung das Attribut separator benutzt. Es gilt als Trennung zwischen den beiden angezogenen Elementen Anrede und Vorname. Wird kein Vorname angezogen, weil keiner im Feld abgefüllt ist, wird der definierte Separator nicht ausgegeben:
<CustomDataNode id="FirstLastNameAndTitle">
<Line>
<Element id="Profile.User.Salutation" separator=" " />
<Element id="Profile.User.FirstName" separator=" " />
<Element id="Profile.User.LastName" />
</Line>
<Line>
<Element id="Profile.Org.Title" />
</Line>
</CustomDataNode>Mit einer Condition können Bedingungen in die Skripte eingebaut werden:
<CustomDataNode id="ConditionBeispiel">
<Line>
<Element id="Profile.User.Salutation" separator=" " />
<!-- Condition direkt auf dem Element / UND-Verknüpfung ↓ -->
<Element when="CustomElements.ShowFirstName = 'true' + CustomElements.DontShowFirstName = 'false'" id="Profile.User.FirstName" />
<Element id="Profile.User.LastName" />
</Line>
<Condition notwhen="CustomElements.ShowTitle = 'false'">
<Line>
<Element id="Profile.Org.Title" />
</Line>
</Condition>
</CustomDataNode>Mit dem Snippet-Element können in der Datenbank gespeicherte primedocs-Textbausteine angezogen werden.
WARNUNG
Bei der Verwendung von Snippet handelt es sich um ein Snippetskript. Dieses kann nicht mit Texten (z. B. mit Element) oder Bildern (Image) gemischt werden. Siehe “Verschiedene Skript-Arten”.
Zudem sollte bei der Anwendung von Snippetskripts unbedingt folgende Seite aus den Best Practices beachtet werden: Einfügen von Snippetskripts in Inhaltsvorlagen.
Dem CustomDataNode-Element wird im unteren Beispiel das Attribut update mitgegeben. update bewirkt mit true, dass der Textbaustein sich in Abhängigkeit von Dokument-Parameter-Auswahlen aktualisiert oder nicht (false).
Verschiedene Skript-Arten
Es gibt drei verschiedene Arten von Skripts, die nicht vermischt werden dürfen:
Skript-Art | Beschreibung |
|---|---|
Textskript | Das Resultat ist ein Text. |
Snippetskript | Das Resultat ist eine Zusammensetzung von Textbausteinen. |
Imageskript | Das Resultat ist ein Bild. |
Grundgerüst eines Skripts
Script-Element
Folgende Zeilen sind standardmässig in jeder Standard-Skript-Dokumentfunktion hinterlegt:
Die dritte Zeile ermöglicht, dass Skripte bzw. dynamische Binding-Elemente überhaupt in Vorlagen verwendet werden können. Hier ist eine Übersicht über die möglichen Attribute:
Attribut | Beschreibung |
|---|---|
depth | Bestimmt, wie oft das Skript-Resultat berechnet wird. Generell wird die Verknüpfung mit der in den Globalen Konfigurationen hinterlegten Depth empfohlen, die standardmässig 5 beträgt. Greif ein Skript auf das Resultat eines anderen Skripts zu, muss |
engine | Bestimmt die Engine, die für die Scriptinterpretation bzw. -umsetzung zur Anwendung kommt. Als Wert steht nur "XSL" zur Verfügung. |
version | Bestimmt die Scriptengine-Version, die zur Anwendung kommt. Standardmässig ist der Wert 2. Die Angabe dieser Version könnte auch auf Ebene |
CustomDataNode-Element
Mittels CustomDataNode wird ein neues Binding-Element erstellt, in welchem dann der Skriptinhalt definiert wird.
Attribut | Beschreibung |
|---|---|
id | Id des Binding-Elements, das definiert wird. Die Id muss eindeutig sein. Für eine bessere Übersichtlichkeit im Vorlagen-Editor kann die Ordnerstruktur selber gesteuert werden: Enthält eine Id einen Punkt, wird aus dem Wort vor dem Punkt ein Ordner erzeugt. primedocs setzt dazu vor jede Id den Präfix "CustomElements.". Das muss beachtet werden, wenn in einem Skript auf ein anderes Skript zugegriffen wird. |
version | Bestimmt die Script-Engine-Version, die zur Anwendung kommt. Eine Angabe auf Ebene |
bookmarkname | Ermöglicht das Festlegen des Namens der Textmarke (Bookmark), in welche die entsprechenden Textbausteine (Snippets) eingefügt werden. die im Vorlageneditor eingefügt wird. Dieses Attribut wird nur im Zusammenhang mit Textbausteinen berücksichtigt. |
update | Bewirkt mit |
Elemente innerhalb von CustomDataNodes und ihre Attribute
Line
Mittels Line-Element werden mehrere Zeilen in einem Skript erzeugt. Alle Elemente, die weiter unten erklärt werden, werden in den meisten Fällen innerhalb von den Line-Start- und Endtags definiert. Wenn in einer Zeile kein Element verfügbar ist, wird sie nicht angezeigt.
Attribut | Beschreibung |
|---|---|
fixoutput | Mittels |
Text
Mittels Text werden Fixtexte ausgegeben.
Element
Mittels Element werden Felder aus primedocs angezogen. Die angezogenen Daten können mittels den folgenden Attributen ergänzt oder formatiert werden:
Attribut | Beschreibung |
|---|---|
id | Id des Feldes, das eingefügt werden soll |
checkBoxActivatedSymbol | Definition des Zeichens, das bei einer angewählten Checkbox ausgegeben werden soll |
checkBoxDeactivatedSymbol | Definition des Zeichens, das bei einer nicht angewählten Checkbox ausgegeben werden soll |
linePrefix | Präfix-Zeichen für jede Zeile einer Liste bzw. eines mehrzeiligen Text-Elements |
separator | Trenntext zum nächsten Element oder Text, der nur angezeigt wird, wenn das nachfolgende Element einen Inhalt liefert. |
showEmptyEndLines | Übernimmt alle vorhandenen nachgestellten Leerzeilen: |
showEmptyStartLines | Übernimmt alle vorhandenen vorangestellten Leerzeilen: |
textafter | Fixtext, der immer hinter dem Element erscheint. z. B. |
textbefore | Fixtext, der immer vor dem Element erscheint. z. B. |
when | siehe Condition |
notwhen | siehe Condition |
Funktionen |
|
fCase* | Definiert, ob der einkommende Text gross ( |
fFormattingDate* | Definiert ein explizites Format für ein DateTime-Element. Generell wird immer mit den in den Globalen Übersetzungen vorhandenen Formaten verknüpft: |
fFormattingNumber* | Definiert ein explizites Format für Telefonnummern in einem Textfeld (z. B. im Feld "Profile.User.Phone"). z. B. |
fFormattingNumeric* | Definiert ein explizites Format für Nummern. |
fReplace* | Definiert, ob ein Teil des Textes ersetzt werden soll. |
fSelectLine* | Definiert, ob aus einem mehrzeiligen Text eine oder mehrere Zeilen selektiert werden sollen. |
fSubstring* | Definiert, ob nur ein Teil des Textes ausgegeben werden soll. |
fSubstringAfter* | Definiert, ob nur das Ende (nach einer bestimmten Zeichekette) des Textes ausgegeben werden soll. Ist das Trennzeichen nicht vorhanden wird der ganze Text ausgegeben. |
fSubstringAfterOrEmpty* | Definiert, ob nur das Ende (nach einer bestimmten Zeichenkette) des Textes ausgegeben werden soll. Ist das Trennzeichen nicht vorhanden wird kein Text ausgegeben. |
fSubstringBefore* | Definiert, ob nur der Anfang (vor einer bestimmten Zeichenkette) des Textes ausgegeben werden soll. Ist das Trennzeichen nicht vorhanden wird der ganze Text ausgegeben. |
fSubstringBeforeOrEmpty* | Definiert, ob nur der Anfang (vor einer bestimmten Zeichenkette) des Textes ausgegeben werden soll. Ist das Trennzeichen nicht vorhanden wird kein Text ausgegeben. |
fTrim* | Definiert, ob nur eine maximale Anzahl an Zeichen ausgegeben werden soll. |
fTrimURL* | Definiert, ob nur ein Teil einer URL oder eines Dateipfades ausgegeben werden soll (siehe auch fTrim). z. B. |
*Dieses Attribut kann beliebig oft hintereinander in einem Element platziert werden. In diesem Fall muss jedes Attribut mit weiteren Zeichen ergänzt werden, damit jeder Befehl eindeutig ist. Im folgenden Beispiel sind die fReplace-Attribute durchnummeriert:
Condition
Mittels Condition können ganze Bereiche anhand von Bedingungen aktiviert oder deaktiviert werden. Die Bedingungen werden in der Regel an Auswahlen im Dokument-Parameter geknüpft. Beispiel: "Wenn die Checkbox "DocParam.Checkbox1" im Dokument-Parameter aktiviert ist, wird ein Text eingeblendet." Es können Text-, CheckBox-, ComboBox- und Image-Elemente validiert werden. Verfügbare Attribute für dieses Element sind when und notwhen.
Attribut | Beschreibung |
|---|---|
when | Bedingung, damit die beinhalteten Elemente und Texte angezeigt werden. Bei der Angabe von Ids (ohne Textvergleichoperatoren, siehe unten) wird geprüft, ob das primedocs-Element mit der Id existiert und einen Inhalt hat. CheckBox Verhalten: Image Verhalten: Möchte man abfragen, ob bestimmte Bilddaten gesetzt oder "leer" sind und nur ein Bild "selektieren", muss man über eine direkte Condition gehen: |
notwhen | Analog dem when-Attribut, jedoch invertiert. |
Vergleichoperatoren
In einem when- oder notwhen-Attribut können auch Vergleichsoperatoren verwendet werden, wobei Fixtexte in einfachen Anführungszeichen ' stehen müssen:
Attribut | Beschreibung |
|---|---|
| Der Inhalt wird 1:1 verglichen |
| Der Inhalt wird ohne Berücksichtigung von Gross-/Kleinschreibung und Leerzeichen verglichen |
| Prüfung ob der Inhalt eine bestimmte Zeichenkette enthält (an beliebiger Position) |
| Prüfung ob der Inhalt mit bestimmten Zeichen beginnt |
| Vergleich der Anzahl Zeichen |
| Prüfung ob die Zeichenanzahl grösser ist |
| Prüfung ob die Zeichenanzahl kleiner ist |
Snippet
Mittels Snippet-Element können in primedocs gespeicherte Textbausteine verwendet oder fixe Inhalte abgefüllt werden.
ACHTUNG
Bei der Verwendung von Snippet handelt es sich um ein Snippetskript. Dieses kann nicht mit Texten (z. B. mit Element) oder Bildern (Image) gemischt werden. Siehe “Verschiedene Skript-Arten”.
Zudem sollte bei der Anwendung von Snippetskripts unbedingt folgende Seite aus den Best Practices beachtet werden: Einfügen von Snippetskripts in Inhaltsvorlagen.
List
Mittels List kann eine dynamische Liste von Elementen ausgegeben werden. Meistens wird das Element für die Anzeige einer Empfängerliste (z. B. in einem Protokoll) zur Anwendung. Innerhalb einer Liste können wieder die Attribute Line, Element und Condition verwendet werden. Die Adressierung der Ids wird nun relativ gemacht, das heisst, dass nun anstelle von Contact.Recipient.Selected.Person.FirstName nur noch Person.FirstName verwendet wird.
Attribut | Beschreibung |
|---|---|
filter | Es gibt folgende Filterkriterien: "An", "Cc", "Bcc". Wird "An" verwendet, werden nur die Empfänger, die unter "An" gewählt wurden, angewendet. |
includeSelected | Bestimmt, ob der aktuell selektierte Kontakt auch in der Liste angezeigt wird oder nicht: |
separator | Trenntext, der immer zwischen den Elementen angezeigt wird |
type | Bestimmt den Listentyp: immer |
Link
Mittels Link kann ein HTML-Link erzeugt werden. Es gilt zu beachten, dass keine anderen daten-anziehenden Elemente im selben Skript verwendet werden sollten. Die Links können nur in HTML-E-Mails und nicht in Kombination mit den normalen Text-Skripten verwendet werden. Es können sowohl primedocs-Felder als auch andere Links hinterlegt werden. Sollten mehrere Link-Elemente auf verschiedenen Zeilen ausgegeben werden, muss das Zeilenende mit   markiert werden.
Attribut | Beschreibung |
|---|---|
id | Id des Feldes, das als URI verwendet werden soll. Wie erwähnt, kann auch ein fixer Link als Taginhalt angegeben werden |
type | Linktyp – Art des Links. Erlaubt sind: |
text | Fixtext, der (sofern abweichend von der URI) angezeigt werden soll. Er wird nur angezeigt, wenn kein Binding-Text vorhanden ist. |
bindingText | Id des Binding-Elements, das als Link-Text angezeigt werden soll |
style | CSS-Styleangaben für die Formatierung des HTML-Links |
styleName | Name einer nicht standardmässig integrierten Formatvorlage vom Typ "Zeichen" (engl.: name of a non-built-in style of type "character"). Sie basiert optimalerweise auf der Formatvorlage "Hyperlink". |
when | siehe Condition |
notwhen | siehe Condition |
Bilder-Links
Mit Link können auch mit einem Link belegte Bilder eingefügt werden.
Bild aus primedocs-Feld:
Fixes Bild:
Attribut | Beschreibung |
|---|---|
bindingImage | Id des Bildes, das angezeigt werden soll, z. B. |
imageSize | Höhe des Bildes, z. B. |
imageDataBase64 | Daten des Bildes im Base64-Format |
imageAltText | Alternativtext, z. B. "Profilbild" / "Profile Image" |
TIPP
Häufig konvertiert Outlook E-Mail-Bilder vor dem Versenden, was zu sichtlich schlechter Bildqualität führen kann. Damit dies bei PNG-Bilddateien weniger passiert, sollten diese mit der Bittiefe 32 abgespeichert werden.
Dies betrifft sowohl Bilder, die hinterlegt sind und über bindingImage abgerufen werden wie auch Bilder, die mit imageDataBase64 direkt angegeben werden.
Die Bittiefe von PNG-Bilddateien wird im Windows Explorer in den Eigenschaften unter "Details – Bild – Bittiefe" (engl. "Details – Image – Bit depth") angezeigt.
Image
Mittels Image können Bilder, die in primedocs bei den Benutzereinstellungen hinterlegt sind, angezogen werden. Durch das "when"-Attribut kann dieses z. B. je nach Auswahl im Dokument-Parameter ein- und ausgeblendet werden.
Referenzierte Bilder müssen in der müssen in der Profildaten-Konfiguration angegeben werden.
PrimeSoft AG, Bahnhofstrasse 4, 8360 Eschlikon, Switzerland