Zum Hauptinhalt gehen
### Kennen Sie schon unsere Bookings-Seite? ### Hier entdecken
Anmelden

Allgemeine Platzhalterhinweise

  • Aktualisiert

Das Schreiben von Daten aus All4Schools in Report-Dateien erfolgt unter Zuhilfenahme von Platzhaltern. Hier finden Sie die wichtigsten Informationen zu ihrer Verwendung.

Allgemeine Informationen zum Erstellen von Reports, Berichten und Dokumenten entnehmen Sie bitte folgender Seite: Reports, Berichte und Dokumente mittels Reportvorlagen erstellen

Inhaltsverzeichnis:

  1. Einführung
  2. Standardformat
  3. Gruppen
  4. Zahlen- und Datumsformatierung
  5. Vergleiche
  6. Platzhalter-Verschachtelung
  7. Reportplatzhalter
  8. Reportplatzhalter-Funktionen
  9. Bildplatzhalter
  10. QR-Codes
  11. Weitere Dokumentationen zu Platzhalter

 

Einführung

Das Schreiben von Daten aus All4Schools in Report-Dateien erfolgt unter Zuhilfenahme von Platzhaltern. Bei der Reporterzeugung werden alle Platzhalter im Vorlagendokument (eine Microsoft Word oder Excel-Datei) ermittelt und durch die entsprechenden Werte ersetzt. Wird kein Wert für einen Platzhalternamen gefunden, wird der Platzhalter einfach entfernt. Darüber hinaus bieten Platzhalter weiterführende Vergleichsfunktionalitäten, welche in diesem Dokument erläutert werden.

Platzhalternamen werden einerseits vom System vorgegeben:

  • Schülerstammdaten
  • Absenzinformationen

und können andererseits vom Anwender frei konfiguriert werden:

  • Schüler-Metafelder
  • Prüfungsplan-Noten
  • Prüfungsplan-Regeln
  • Report-Parameter

Eine komplette Übersicht der zur Verfügung stehenden Platzhalter für Zeugnisvorlagen findet sich hier.

 

Standardformat

Ein in der Vorlage verwendeter Platzhalter muss in folgender Form angegeben werden:

###Platzhaltername###

Ein im All4Schools vom Anwender definierter Platzhaltername wird ohne die vor- und nachgestellten ### gepflegt. Die ### müssen nur im Vorlagendokument geschrieben werden und dienen der eindeutigen Identifizierung der Platzhalter.

Eingeschränkt kann anstelle von ### auch §§§ verwendet werden. Mehr dazu finden sie im Abschnitt Platzhalter-Verschachtelung

Auf Schüler-Metafelder kann über den Metafeldnamen oder den optionalen Metafeld-Schlüssel zugegriffen werden. Der Schlüssel darf keine Leerzeichen enthalten. Leerzeichen im Namen werden durch _ ersetzt. Heißt ein Metafeld bspw. "Bemerkung Zeugnis" mit Schlüssel "BemZeug" muss der zugehörige Platzhalter im Vorlagendokument folgendermaßen aussehen:

###Bemerkung_Zeugnis### = Zugriff über Namen
oder
###BemZeug### = Zugriff über Schlüssel
 

Gruppen

Durch Gruppen können zusammengehörende Platzhalter definiert werden, die nur geschrieben werden, wenn alle Platzhalter der Gruppe einen Wert besitzen. Wird bpsw. im Prüfungsplan für eine Note im Fach Deutsch der Platzhaltername "DE" definiert, so kann über ###DE.Name### der im Prüfungsplan angegebene Name und über ###DE.Value### die zugehörige Note ermittelt werden. Je nach Anforderung kann es sein, dass der Fachname nur geschrieben werden soll, wenn der Schüler auch eine Note in diesem Fach vorweisen kann bzw. er dieses Fach belegt hat. Dies kann durch die Angabe einer Gruppe realisiert werden:

###Gruppenname:Platzhaltername###

für den Fall im Fach Deutsch:
    
###Grp1:DE.Name### und ###Grp1:DE.Value###

Beide Platzhalter besitzen den Gruppennamen "Grp1" und sind damit in der gleichen Gruppe. Der Gruppenname kann frei gewählt werden, darf jedoch keine Leerzeichen enthalten. Es können beliebig viele Gruppen gebildet werden. Nur wenn alle Platzhalter der Gruppe einen Wert enthalten werden die Platzhalter ins Dokument geschrieben. Anderenfalls werden die Platzhalter einfach entfernt.

Eine Besonderheit gilt für Word-Tabellen. Muss ein Gruppenplatzhalter in einer Tabellenzeile entfernt werden, weil dieser oder ein anderer Platzhalter dieser Gruppe keinen Wert besitzt, so wird die gesamte Tabellenzeile gelöscht. Damit lassen sich dynamische Tabellen realisieren, die bspw. nur die Fächer enthalten, die ein Schüler auch belegt hat.

 

Zahlen- und Datumsformatierung

Zeugnisnoten werden in der Regel über einen Prüfungsplan dem Report zur Verfügung gestellt. Auf die berechneten Noten des Prüfungsplans kann über die .Value-Eigenschaft des vergebenen Platzhalternamens zugegriffen werden:

###DE.Value###

Unabhängig von der Rundung der Note kann die Note hinsichtlich ihrer Nachkommastellen formatiert werden:

###Platzhaltername.Value|Formatierungsangabe

###DE.Value|F2### = 2 Nachkommastellen

z.B.
###DE.Value|P### = Zahl mit 100 multipliziert und mit Prozentzeichen versehen

Ein komplette Liste der möglichen Formatierungsangaben finden sie hier.

Ohne Formatierungsangabe werden die Noten ohne Nachkommastelle ausgegeben. Beachten sie, dass die Noten beim Formatieren gerundet werden! Eine im Prüfungsplan auf Zehntel gerundete Note, die ohne Nachkommastelle im Report ausgegeben wird, wird bei der Formatierung mathematisch auf eine Ganzzahl gerundet. Um Missverständnisse zu vermeiden, sollten sie sicherstellen, dass die im Prüfungsplan verwendete Rundung der Ausgabe im Report entspricht.

Datumsformatierung

###Platzhaltername|Formatierungsangabe

z.B.
{ 'PLACEHOLDER_COMMON_Chpt4_11' | translate }

Ein komplette Liste der möglichen Formatierungsangaben finden sie hier.

 

Vergleiche

Neben der herkömmlichen Ausgabe der Platzhalterwerte können die Werte auch mit Vorgaben verglichen werden. Sind die verglichenen Werte gleich, wird ein Text X ausgegeben, sind sie nicht gleich Text Y. Damit kann man bpsw. einen Leerstrich im Dokument realisieren, wenn eine Note nicht gegeben ist oder umgekehrt ein nachgestelltes Prozentzeichen, wenn die Note vorhanden ist. Ein Vergleich wird ähnlich bekannter Programmiersprachen durch == und dem Kurzoperator ? realisiert:

###Platzhaltername=="Vergleichswert"?"Wert wenn Platzhalterwert und Vergleichswert gleich":"Wert wenn ungleich"###

Für eine bessere Übersicht können auch Leerzeichen innerhalb des Platzhalters verwendet werden:

### Platzhaltername == "Vergleichswert" ? "Wert wenn Platzhalterwert und Vergleichswert gleich" : "Wert wenn ungleich" ###

Um beispielsweise einen Leerstrich auszugeben, wenn eine Note nicht gesetzt ist kann folgender Platzhalter verwendet werden:

### DE.Value == "" ? "-" : "" ###

Wortwörtlich bedeutet die Schreibweise: Wenn der Wert von DE.Value leer ist, dann schreibe - sonst schreibe nichts. Der gleiche Vergleich kann verwendet werden, um bei vorhandener Note/Wert ein Prozentzeichen zu schreiben:

### DE.Value == "" ? "" : "%" ###

Wenn der Wert von DE.Value leer ist, dann schreibe nichts, sonst schreibe %. Durch Kombination mit einem zweiten Platzhalter, der den eigentlichen Wert der Note ausgibt, kann die Ausgabe komplettiert werden:

###DE.Value######DE.Value==""?"-":"%"###

DE.Value=2 = Ausgabe: 2%
DE.Value nicht gesetzt = Ausgabe: -

Da die oben genannte Kombination recht häufig vorkommt, exisitert im All4Schools für diesen Fall eine Kurzschreibweise:

### Platzhaltername ? "Wert, der angehangen wird, wenn Platzhalterwert gesetzt ist" : "Wert, der angezeigt wird, wenn Platzhalterwert nicht gesetzt ist" ###

Umgemünzt auf den obigen Fall der Prozentausgabe bei vorhandenem Wert bzw. - bei nicht Vorhandensein ergibt dies:

###DE.Value?"%":"-"###

Neben dem Gleichheits-Operator == existert ein ähnlicher Operator ˜= , mit dem überprüft werden kann, ob der Platzhalterwert den Vergleichswert enthält. Ansonsten ist er genauso zu verwenden wie ==.

### Bemerkung ~= "bestanden" ? "1" : "" ###

Wenn der Wert des Platzhalters Bemerkung die Zeichenkette "bestanden" enthält, gib 1 aus, sonst nichts.

Darüber hinaus existieren Vergleichsoperatoren speziell für Zahlen:

>
<
>=
<=

Wenn der Platzhalterwert und der Vergleichswert (beides Zeichenketten) jeweils in eine Zahl umgewandelt werden kann, wird der Operator angewendet, ansonsten schlägt der Vergleich immer fehl und die zweite Zeichenkette nach dem ? wird als Ergebnis zurückgeliefert.

 

Platzhalter-Verschachtelung

Im vorherigen Abschnitt wurden die Vergleichswerte immer fest in der Platzhalterdefinition angegeben. Ebenso die Ausgabewerte, wenn der Vergleich erfolgreich ist bzw. wenn nicht. Diese festen Werte können ebenfalls durch Platzhalter realisiert werden. Dazu ist es notwendig, dass die Platzhalter verschachtelt werden.

Um die Verschachtelung zu verstehen, muss zunächst die eigentliche Platzhalterersetzung etwas genauer erläutert werden. Im Rahmen der Reporterzeugung wird das Vorlagendokument zweimal hintereinander auf Platzhalter durchsucht und diese werden ersetzt. Dadurch kann sichergestellt werden, dass Platzhalterwerte, die ihrerseits ebenfalls Platzhalter enthalten, ausgegeben und die darin enthaltenen Platzhalter ersetzt werden. Als Beispiel ist hier ein Auswahl-Metafeld für vordefinierte Bemerkungen zu nennen, welches den Namen des Schülers als Platzhalter enthält. Im zweiten Ersetzungsdurchlauf gilt jedoch eine Besonderheit. Neben den Platzhaltern, die durch ### eingefasst sind, werden zusätzlich auch Platzhalter mit §§§ anstatt ### berücksichtigt. Damit ist es möglich Platzhalter zu erstellen, die erst im zweiten Durchlauf berücksichtigt werden, dann aber schon ersetzte Werte aus dem ersten Durchlauf verwenden. Besser erläutern lässt sich dies an einem konkreten Beispiel. Gegeben sind vier Text-Metafelder par1 bis par4:

§§§ par1 ~= "###par2###" ? "###par3###" : "###par4###" §§§

Wenn der Wert von par1 den Wert von par2 enthält, dann gib den Wert von par3 aus, sonst den Wert von par4. Angenommen es gelten folgende Werte:

par1 = Der Teilnehmer hat den Kurs erfolgreich bestanden
par2 = erfolgreich bestanden
par3 = Herzlichen Glückwunsch
par4 = Viel Glück beim nächsten Mal

Nach dem ersten Ersetzungsdurchlauf ergibt sich im Vorlagendokument folgender Platzhalter:

§§§ par1 ~= "erfolgreich bestanden" ? "Herzlichen Glückwunsch" : "Viel Glück beim nächsten Mal" §§§

Nach der zweiten Ersetzung:

Herzlichen Glückwunsch

Mit par1 = "Der Teilnehmer hat den Kurs nicht bestanden" ergibt sich stattdessen

Viel Glück beim nächsten Mal

 

Reportplatzhalter

Wie in den oberen Beispielen ersichtlich, können Platzhalterangaben schnell recht lang werden. Insbesondere die Ausgabe von Noten mit Formatierungen bzw. Alternativwerten wenn nicht gesetzt, erfolgt meist in kleinen Textfeldern im Vorlagendokumen. Durch den langen Platzhaltertext kommt es schnell zu Umbrüchen, die nach der Ersetzung zwar verschwunden sind, während des Vorlagendesigns jedoch das Gesamtbild verzerren. Aus diesem Grund gibt es Reportplatzhalter, mit denen eine Platzhalterdefinition abgekürzt werden kann.

Reportplatzhalter werden einmalig vor der eigentlichen Platzhalterersetzung auf des Dokument angewendet. Sie bestehen aus einem Schlüssel, ähnlich des Platzhalternamens und einem Wert, mit dem der Schlüssel ersetzt werden soll. Anders als bei den herkömmlichen Platzhaltern müssen die Schlüssel der Reportplatzhalter bei der Verwendung in der Templatevorlage nicht mit ### oder §§§ eingefasst werden. Wichtig dabei ist jedoch, dass die Schlüssel eindeutig definiert werden. Eine Angabe von "K" als Abkürzung für einen Klassennamen und "KGrade" für die Klassenstufe ist nicht eindeutig, das "KGrade" auch "K" enthält. Wird statt "K" aber "[K]" angegeben, ist es wieder eindeutig. Natürlich müssen die Schlüssel auch eindeutig gegenüber dem restlichen Inhalt der Vorlage sein, damit nicht unvorhergesehene Textersetzung durchgeführt werden.

Schlüssel = [DE]
Ersetzungs-Wert = ###DE.Value?"%":"-"###

Alle Zeichenketten [DE] im Vorlagendokument werden mit ###DE.Value?"%":"-"### ersetzt. Statt 22 Zeichen werden nur noch 4 Zeichen benötigt, und dennoch ist der kurze Schlüssel fachlich noch gut zu interpretieren.

 

Reportplatzhalter-Funktionen

Das Beispiel im vorherigen Abschnitt zeigt, wie ein langer Platzhalter eingekürzt werden kann. Sollen wie in dem Beispiel neben dem Fach Deutsch noch weitere Fächernoten-Platzhalter auf die gleiche Weise eingekürzt werden, entstehen schnell viele sehr ähnliche Reportplatzhalter. Zum Beipiel:

[DE] = ###DE.Value?"%":"-"###
[MA] = ###MA.Value?"%":"-"###
[EN] = ###EN.Value?"%":"-"###
usw.

Die Systematik der Platzhalter ist in diesem Beispiel immer die gleiche. Anstatt für jedes Fach einen eigenen Reportplatzhalter zu erstellen, kann stattdessen eine Reportplatzhalter-Funktion definiert werden. Funktionen besitzen einen Funktionsnamen gefolgt von einer von Klammern umschlossenen kommaseparierten Parameterliste:

Funktionsname( Parameter1, Parameter2, Parameter3 )

Die Parameternamen der Funktion können dann im Reportplatzhalter-Wert verwendet werden. Es können beliebig viele Parameter definiert werden, die durch Kommas voneinander getrennt sind. Eine Funktion, die unsere Fächernotenplatzhalter abbildet, würde folgendermaßen aussehen:

Note(Platzhalter) = ###Platzhalter.Value?"%":"-"###

oder noch kürzer

N(Platzhalter) = ###Platzhalter.Value?"%":"-"###

Im Vorlagendokument kann sie anschließend verwendet werden (die kürzere Variante):

N(DE)
N(MA)
N(EN)
usw.

Während der Ersetzung der Reportplatzhalter wird mittels regulärem Ausdruck nach dem Funktionsnamen inkl. Parameterliste im Dokument gesucht, die Parameterwerte bestimmt, alle Parameterangeben im Platzhalterwert mit diesen Parameterwerten ersetzt und anschließend der Reportplatzhalter-Schlüssel mit dem finalen Reportplatzhalter-Wert ersetzt. Hier noch ein weiteres Beispiel:

Note(Platzhalter,Vergleichswert) = ###Platzhalter.Value=="Vergleichswert":"x":""###

Die Funktion erwartet einen Prüfungsplanplatzhalter mit .Value-Eigenschaft. Wenn der Wert der Value-Eigenschaft gleich dem Vergleichswert ist, wird x ausgegeben, sonst nichts. Im Vorlagendokument kann die Funktion verwendet werden:

Note(DE,1)

Wenn die Note im Fach Deutsch 1 ist, wird x ausgeben, sonst nichts. Während der Ersetzung der Reportplatzhalter wird im Dokument die Funktion gefunden:

Note(DE,1)

Parameter Platzhalter = DE
Parameter Vergleichswert = 1

Anschließend werden die Parameterwerte im Reportplatzhalterwert ersetzt:

aus ###Platzhalter.Value=="Vergleichswert":"x":""###
wird ###DE.Value=="1":"x":""###

Im Vorlagendokument wird nun die Funktion mit dem ersetzten Reportplatzhalterwert ersetzt:

Note(DE,1) = ###DE.Value=="1":"x":""###

Beachten sie, dass die Ermittlung der Funktionen mittels regulärem Ausdruck erfolgt. Besteht der Funktionsplatzhalter aus Zeichen, die im regulären Ausdruck eine besondere Bedeutung haben, bspw. die eckigen Klammern, müssen diese Zeichen mit "/" "escaped" werden:

statt [Note](Parameter) = /[Note/](Parameter)

 

Bildplatzhalter

Neben den herkömmlichen Platzhaltern mit textuellem Inhalt bietet das Reportingsystem zudem die Möglichkeit, Anhänge und Schülerfotos als Bild in den Report zu integrieren. Im Unterschied zu fest in die Vorlage integrierten Bildern, können mittels Bildplatzhalter Bilder dynamisch und pro Enitität verschieden in den Report integriert werden. Unterstützt werden alle Bilder, die als Anhang hinterlegt sind. Da Schülerfotos intern als Anhang gespeichert werden, können auch diese problemlos integriert werden. Einige Beispiele:

[img2;###CrmId###] = Schülerfoto pro Schüler, die Id ist durch die Verwendung des Platzhalter ###CrmId### dynamisch

[img2;1234;40;30] = Schülerfoto fest vom Schüler mit der Id 1234, das Bild hat die Höhe von 40px sowie Breite von 30px

[img6;###CrmId###;40;30;Unterschrift] = Bild aus Anhang eines CrmEntities, dessen Bildname (Name beim Upload) die Zeichenkette "Unterschrift" enthält

Der Platzhalter hat somit folgende Form:
[img[Anhangstyp];[Objekt-Id];[Bildhöhe - optional];[Bildbreite - optional];[Dateiname-Filtertext]]

Hinweis: Bildplatzhalter funktionieren nur in Word-Vorlagen. Die Bilddateien werden optimal angezeigt werden, wenn sie sich in einer Tabellenzelle befinden. Die Tabelle kann dabei einzig zum Zweck des Bildes mit einer Spalte und einer Zeile angelegt werden. Über die Tabelle erfolgt gleichzeitig die Platzierung des Bilds in der Vorlage.

Folgende Anhangstypen stehen derzeit zur Verfügung:

  • 2 = Schülerfoto
  • 5 = Kurs
  • 6 = CrmEntity (außer Schüler, also Eltern, Firmen, Mitarbeiter etc.)
  • 7 = Schüler

Die Objekt-Id bezieht sich immer auf das Objekt, an dem der Anhang hinterlegt ist. Es handelt sich dabei um die eindeutige technische Id (Ganzzahl, ersichtlich am Ende der Url des Datensatzes). In der Regel ist es somit die Crm-Id, bei Kursen die Kurs-Id.<br/>Die Platzhalterersetzung erfolgt bei der Erzeugung eines Reports zweimal. Damit hat man die Möglichkeit im zweiten Durchgang bestimmte Bedingungen und Paramter von anderen Platzhaltern, die im ersten Durchgang ersetzt wurden, abhängig zu machen. Die Bildplatzhalter werden erst im zweiten Durchgang verarbeitet. Dadurch hat man die Möglichkeit, bspw. die Schüler-Id mittels Platzhalter ###CrmId### dynamisch zu übergeben. Es ist auch denkbar, dass bpsw. im Schülerbericht das Bild der Unterschrift des Klassenlehrers ermittelt wird. Man ist in dem Fall somit nicht auf die Anhänge des Schülers beschränkt, sondern kann auf alle Anhänge (Bilder) aller Objekte zugreifen, auf die man über den Schüler bspw. per Relation Zugriff hat.

Wird die Filter-Option auf den Dateinamen verwendet, können durch die Enthält-Prüfung durchaus mehrere Anhangs-Bilder in Frage kommen. Der Bildplatzhalter wählt in jedem Fall immer das erste Bild, welches er aus der Datenbank heraus ermittelt.

Hinweis: Die Bilderzeugung mittels Bildplatzhalter ist damit sehr dynamisch. Dies führt jedeoch dazu, dass entgegen der anderen Platzhalterwerte, die für alle Entitäten zusammen ermittelt werden, bei den Bilder für jede Entität einzeln eine Abfrage erfolgt. Dies kann sich negativ auf die Performance auswirken.

 

QR-Codes

Über den QR-Code-Platzhalter können textuelle Inhalte in einem CR-Code codiert in den Report geschrieben werden. Einige Beispiele:

[qrhttps://www.google.de] = URL-Verweise auf die Google-Suchmaschine

[qr###Url###;100;100] = URL-Verweise auf URL, die im Metafeld Url hinterlegt ist, Höhe und Breite sind auf 100px gesetzt

[qrmailto:###Email###?subject=Anfrage&body=Rückmeldung] = Mailto-Link für Kontaktaufnahme

[qrhttps://maps.google.com/maps?q=###Latitude###,###Longitude###] = Google-Maps-Link für Firmenstandort, Latitude und Longitude müssen in dem Fall Metafelder an der Firma sein

Hinweis: QR-Codeplatzhalter funktionieren nur in Word-Vorlagen. Sie werden zudem nur aufgelöst, wenn sie sich in einer Tabellenzelle befinden. Die Tabelle kann dabei einzig zum Zweck des QR-Codes mit einer Spalte und einer Zeile angelegt werden. Über die Tabelle erfolgt gleichzeitig die Platzierung des QR-Codes in der Vorlage.

 

Weitere Dokumentationen zu Platzhalter

 

Verwandte Beiträge