font(...)
Inhaltsverzeichnis |
Mithilfe der Funktion font(...) kann ein Text als Grafik gerendert werden, wahlweise auch mit einer Hintergrundgrafik.
Die Parameter der font(...)-Funktion sind ähnlich den Parametern der Font-Funktion.
Im Unterschied zur Font-Funktion kann mit der Funktion font(...) nur ein Textbereich dargestellt werden.
Die Funktion font(...) kann innerhalb einer $CMS_REF(...)$- oder $CMS_VALUE(...)$-Anweisung verwendet werden. |
Die font(...)-Funktion liefert ein Rückgabeobjekt zurück, welches mit einer $CMS_VALUE(...)$-Anweisung Informationen zum erzeugten Bild zurückliefert.
Syntax der font(...)-Funktion
Der Grundaufbau der font(...)-Funktion sieht wie folgt aus:
$CMS_REF(
font(
alpha:WERT,
bounds:"SCHLÜSSELBEGRIFF",
boxjustify:"SCHLÜSSELBEGRIFF",
boxvalign:"SCHLÜSSELBEGRIFF",
color:"FARBE",
filetype:"SCHLÜSSELBEGRIFF",
fractionalmetrics:BOOLESCHER_WERT,
font:"BEZEICHNER",
height:WERT,
justify:"SCHLÜSSELBEGRIFF",
lineheight:WERT,
media:"BEZEICHNER",
resolution:"BEZEICHNER",
size:WERT,
style:"SCHLÜSSELBEGRIFF",
text_antialiasing:BOOLESCHER_WERT,
width:WERT,
xoffset:WERT,
yoffset:WERT,
text:OBJEKT
)
)$
Parameter der font(...)-Funktion
Für die font(...)-Funktion lassen sich folgende Parameter angeben:
Attribute | Bedeutung | mögliche Werte | Pflichtparameter |
---|---|---|---|
Deckungsgrad des Textes | Ganzzahl | nein | |
Hintergrundfarbe des Bildbereiches | Farbwert in Hexdezimalschreibweise | nein | |
Ausmaße des Bildbereiches anpassen | image | nein | |
Horizontale Ausrichtung des Textbereichs | left, center, right | nein | |
Vertikale Ausrichtung des Textbereichs | top, center, bottom | nein | |
Schriftfarbe | Farbwert in Hexdezimalschreibweise | nein | |
Dateityp des erzeugten Bildes | jpg, png, webp | nein | |
Schriftart | Bezeichner | ja | |
Überlagerung von Buchstaben verhindern | Boolescher Wert | nein | |
Höhe des Text- und Bildbereichs | Ganzzahl | nein | |
Horizontale Textausrichtung | left, center, right | nein | |
Zeilenhöhe | Ganzzahl | nein | |
Hintergrundbild; | Bezeichner | nein | |
Schriftgröße | Ganzzahl | nein | |
Schriftstil | Schlüsselwörter | schriftabhängig | |
Darzustellender Text | Zeichen | ja | |
Schriftglättung (Antialiasing) des Texts aktivieren/deaktivieren | Boolescher Wert | nein | |
Breite des Text- und Bildbereichs | Ganzzahl | nein | |
Horizontale Verschiebung des Textbereichs | Ganzzahl | nein | |
Vertikale Verschiebung des Textbereichs | Ganzzahl | nein | |
Beim Parametern text handelt es sich um einen Pflichtparameter. Der Parameter style ist von der verwendeten Schriftart abhängig. Ob es sich dabei um einen Pflichtparameter handelt, ist abhängig von der ausgewählten Schriftart. Alle anderen Parameter sind optionale Parameter. |
Parameter font
Mit dem Parameter font wird angegeben, welche Schriftart für das Rendern des Texts verwendet werden soll. Als Wert des Parameters ist der symbolische Bezeichner (Referenzname) einer im FirstSpirit-Server hinterlegten True-Type-Schrift (Abkürzung: TTF, englisch für True Type Font) anzugeben.
Wird der Parameter nicht angegeben, so wird die Sun-interne Schriftart SansSerif genommen. |
Schriften werden im FirstSpirit-Server über den ServerManager angelegt. Die einzelnen Schritte werden unter Installierte Fonts (→Dokumentation für Administratoren) beschrieben.
$CMS_REF(
font(
font:"BEZEICHNER",
...
text:"..."
)
)$
Parameter height
Mit dem Parameter height wird die Höhe des Textbereiches (siehe Schematische Darstellung) angegeben. Die Angabe der Breite desTextbereiches erfolgt in Pixel.
Im Gegensatz zur Funktion Font ist der Textbereich identisch mit dem Bildbereich, d.h. die angegebenen Höhe entspricht der Höhe des erzeugten Bildes. |
Es erfolgt kein automatischer Umbruch des Textes. |
Der Parameter width hat nur ein Auswirkung mit dem Parameter height. |
Wird der Parameter media angegeben, so hat weder width noch height eine Auswirkung. |
$CMS_REF(
font(
height:WERT,
width:WERT,
...
text:"..."
)
)$
Parameter width
Mit dem Parameter width wird die Breite des Textbereiches (siehe Schematische Darstellung) angegeben. Die Angabe der Breite des Textbereiches erfolgt in Pixel.
Im Gegensatz zur Funktion Font ist der Textbereich identisch mit dem Bildbereich, d.h. die angegebenen Breite entspricht der Breite des erzeugten Bildes. |
Es erfolgt kein automatischer Umbruch des Textes. |
Der Parameter width hat nur ein Auswirkung mit dem Parameter height. |
Wird der Parameter media angegeben, so hat weder width noch height eine Auswirkung. |
$CMS_REF(
font(
height:WERT,
width:WERT,
...
text:"..."
)
)$
Parameter media
Mit dem Parameter media wird das Hintergrundbild festgelegt, auf dem der Textbereich gerendert werden. Das Hintergrundbild legt nicht die Breite und Höhe des erzeugten Bildes fest. Um die Breite und Höhe des erzeugten Bildes vom Hintergrundbild zu übernehmen, ist der Parameter bounds zu verwenden.
Der Parameter erwartet als Wert den Referenznamen eines Bildes aus der Medien-Verwaltung. Dem Referenznamen muss kein media: vorangestellt werden:
$CMS_REF(
font(
media:"BEZEICHNER",
...
text:"..."
)
)$
Handelt es sich beim Bild aus der Medien-Verwaltung um ein transparentes GIF- oder PNG-Bild, so ist auch das erzeugte Bild ein transparentes PNG-Bild. Ansonsten wird ein Bild mit schwarzem Hintergrund erzeugt. |
Parameter text
Mit dem Parameter text wird der Inhalt des Textbereichs angegeben. Die Angabe des Inhaltes kann entweder mit Hilfe von Ausdrücken oder aber als Definition eines Vorlagenfragmentes (vergleichbar mit einer Absatzvorlage) erfolgen.
Ein Bild, welches durch die Funktion font(...) erzeugt wurde, kann nur einen Textbereich enthalten.
Der Parameter ist als letzte Parameter der font(...)-Funktion anzugeben. |
Definition unter Verwendung von Ausdrücken:
$CMS_REF(
...
text:AUSDRUCK
)
)$
Definition unter Verwendung von Konstanten:
$CMS_REF(
...
text:"KONSTANTE"
)
)$
Parameter filetype
Ein Bild, das durch die font(...)-Funktion erzeugt wird, ist standardmäßig eine PNG-Datei (Portable Network Graphics). Der Parameterwert für eine manuelle Angabe lautet: png.
Mit dem Parameter filetype kann statt einer PNG-Datei auch eine
- JPEG-Datei (Joint Photographic Experts Group, Wert: jpg)
- WebP-Datei (Wert: webp)
erstellt werden.
Beispiele:
$CMS_REF(
font(
filetype:"png",
...
text:"..."
)
)$
$CMS_REF(
font(
filetype:"jpg",
...
text:"..."
)
)$
Parameter size
Mit Hilfe des Parameters size kann die Schriftgröße in Punkten (Zeichen: pt) für den Textbereich angegeben werden. Wird der Parameter nicht angegeben, so wird für den Textbereich als Schriftgröße 14 Punkte verwendet.
$CMS_REF(
font(
size:GANZAHL,
...
text:""
)
)$
Parameter bounds
Mit dem Parameter kann die Größe der erzeugten Bildes an die Hintergrundgrafik angepasst werden.
Damit die Größe des erzeugten Bildes der der Hintergrundgrafik entspricht, ist der Schlüsselbegriff image anzugeben.
$CMS_REF(
font(
media:"BEZEICHNER",
bounds:"image",
...
text:""
)
)$
Der Parameter wird nur angewendet, wenn der Parameter media zusätzlich angegeben wurde. |
Wird der Parameter nicht angegeben, hat das erzeugte Bild die Breite und Höhe des Textbereiches, außer die Parameter height und width wurden angegeben.
Parameter text_antialiasing
Mit dem Parameter text_antialiasing kann die standardmäßige Textglättung (Antialiasing) deaktiviert werden.
Um die Textglättung zu deaktiveren, ist für text_antialiasing der Boolesche Wert false anzugeben:
$CMS_REF(
font(
text_antialiasing:false,
...
text:""
)
)$
Parameter fractionalmetrics
Bei der Deaktivierung der Textglättung (siehe Parameter text_antialiasing) kann es bei kleineren Schriftgrößen dazu kommen, dass Buchstaben ineinandergeschoben bzw. überlagert dargestellt werden.
Um diesen Effekt zu unterbinden, gibt es den Parameter fractionalmetrics. Damit Buchstaben nicht ineinandergeschoben bzw. überlagert dargestellt werden, ist für den Parameter der Boolesche Wert false anzugeben.
Wird der Parameter nicht angegeben, so werden die Buchstaben ineinandergeschoben bzw. überlagert dargestellt.
$CMS_REF(
font(
text_antialiasing:false,
fractionalmetrics:false,
...
text:""
)
)$
Parameter bgcolor
Mit dem Parameter bgcolor kann die Hintergrundfarbe für den Bildbereich angegeben werden. Die Angabe erfolgt in sechsstelliger Hexadeximal-Schreibweise mit vorangestelltem # (z. B. #123456). Wird der Parameter nicht angegeben, so wird der Bildbereich mit weißer Hintergrundfarbe (#FFFFFF) erzeugt.
$CMS_REF(
font(
bgcolor:"FARBE",
...
text:""
)
)$
Parameter color
Mit dem Parameter color kann die Schriftfarbe für den Textbereich angegeben werden. Die Angabe erfolgt in sechsstelliger Hexadeximal-Schreibweise mit vorangestelltem # (z. B. #123456). Wird der Parameter nicht angegeben, so wird der Textbereich mit schwarzer Schriftfarbe (#000000) erzeugt.
$CMS_REF(
font(
color:"FARBE",
...
text:""
)
)$
Parameter alpha
Durch den Parameter alpha wird die Deckkraft des Textbereichs in Prozent angegeben. Wird der Wert mit 100 (Standardeinstellung) angegeben, ist die Schrift des Textbereichs vollständig deckend. Wird ein Wert <100 angegeben, wird der Textbereich vor dem Hintergrundbild transparenter, bis er bei einem Wert von 0 vollständig transparent (also nicht mehr sichtbar) ist.
$CMS_REF(
font(
alpha:GANZZAHL,
...
text:""
)
)$
Die Angabe von 0 führt dazu, dass die Schrift vollständig transparent und somit nicht sichtbar mehr ist! |
Parameter lineheight
Mit dem Parameter lineheight wird die Zeilenhöhe einer Zeile (im Textbereich) in Punkten (Einheit: pt) angegeben. Die Vorbelegung dieses Wertes ist der doppelte Wert des size-Parameters.
$CMS_REF(
font(
lineheight:GANZZAHL,
...
text:""
)
)$
Parameter style
Einige Schriftarten unterstützen die Angabe eines speziellen Schriftstils. Mit dem Parameter style lassen sich die einzelnen Schriftstile angeben.
Einige gebräuchliche Schriftstile sind: italic (für Kursiv) und bold (für Fett).
$CMS_REF(
font(
style:"SCHLÜSSELBEGRIFF",
...
text:""
)
)$
Parameter boxjustify
Mit dem Parameter boxjustify wird die horizontale Ausrichtung des Textbereiches auf der Hintergrundgrafik festgelegt. Die Ausrichtung wirkt sich nur auf den Textbereich aus und nicht auf den Inhalt (siehe auch: Schematische Darstellung).
Gültige Werte sind: left (linksbündig = Vorbelegung), center (zentriert) und right (rechtsbündig).
$CMS_REF(
font(
boxjustify:"SCHLÜSSELBEGRIFF",
...
text:""
)
)$
Parameter boxvalign
Mit dem Parameter boxvalign wird die vertikale Ausrichtung des Textbereiches auf der Hintergrundgrafik festgelegt. Die Ausrichtung wirkt sich nur auf den Textbereich aus und nicht auf den Inhalt (siehe auch: Schematische Darstellung).
Gültige Werte sind: top (oben = Vorbelegung), center (mittig) und right (unten).
$CMS_REF(
font(
boxvalign:"SCHLÜSSELBEGRIFF",
...
text:""
)
)$
Parameter justify
Mit dem Parameter justify wird die horizontale Ausrichtung des Textbereich-Inhalts festgelegt. Die Ausrichtung wirkt sich nur auf den Inhalt aus und nicht auf den Textbereich (siehe auch: Schematische Darstellung).
Gültige Werte sind: left (linksbündig = Vorbelegung), center (zentriert) und right (rechtsbündig).
$CMS_REF(
font(
justify:"SCHLÜSSELBEGRIFF",
...
text:""
)
)$
Parameter xoffset
Mit dem Parameter xoffset ist es möglich, den Textbereich auf der Hintergrundgrafik horizontal zu verschieben.
Der Parameter erwartet als Wert eine Ganzzahl. Bei einer negativen Ganzzahl wird der Textbereich nach links, bei einer positiven nach rechts verschoben.
$CMS_REF(
font(
xoffset:GANZZAHL,
...
text:""
)
)$
Parameter yoffset
Mit dem Parameter yoffset ist es möglich, den Textbereich auf der Hintergrundgrafik vertikal zu verschieben.
Der Parameter erwartet als Wert eine Ganzzahl. Bei einer negativen Ganzzahl wird der Textbereich nach oben, bei einer positiven nach unten verschoben.
$CMS_REF(
font(
yoffset:GANZZAHL,
...
text:""
)
)$
Rückabeobjekt
Mit dem Rückabeobjekt der font(...)-Funktionen können mit Methoden Informationen zum erzeugten Bild (z. B. Breite und Höhe) ermittelt werden. Die Methoden können entweder direkt auf dem font(...)-Aufruf angewendet werden:
$CMS_VALUE(font(...).width)$
oder aber in Verbindung mit einer $CMS_SET(...)$-Anweisung:
$CMS_SET(BEZEICHNER, font(...))$
$CMS_VALUE(BEZEICHNER.width)$
Auf folgende Attribute können auf dem Rückgabeobjekt der Funktion font(...) zugegriffen werden:
Attribute | Beschreibung |
---|---|
BEZEICHNER.height | Liefert die Höhe des erzeugten Bildes in Pixel zurück. |
BEZEICHNER.width | Liefert die Breite des erzeugten Bildes in Pixel zurück. |
Beispiele zur Funktion font(...)
Nachfolgend werden einige Beispiele zur Verwendung der Anweisung innerhalb von Vorlagen gezeigt. Die Beispiele sollen die konkrete Auswirkung der Anweisung verdeutlichen und eine Hilfe für den Vorlagenentwickler bei der Erstellung eigener Vorlagen sein.
Für die Verwendung innerhalb eines Projekts, müssen die hier gezeigten Beispiele angepasst werden! Beispielsweise müssen Variablennamen auf die spezifischen Variablennamen des Projekts geändert werden, in dem die Anweisung verwendet werden soll. |
<img src="$CMS_REF(
font(
font:"Arial",
size:14,
filetype:"jpg",
color:"#FF0000",
text:"Schnäppchen"
)
)$" />
Im Beispiel wird mit der Schriftart Arial, in Schriftgröße 14 und in rot ein JPG-Bild mit dem Text Schnäppchen erzeugt.
Das erzeugte Bild sieht so aus:
Zusätzlich kann die Erzeugung des Bildes mit der Ausgabe der Breite und Höhe kombiniert werden:
$CMS_SET(set_font, font(
font:"Arial",
size:14,
filetype:"jpg",
color:"#FF0000",
text:"Schnäppchen"
))$
<img src="$CMS_REF(set_font)$" width="$CMS_VALUE(set_font.width)$" height="$CMS_VALUE(set_font.height)$" />
Eine exemplarische Ausgabe würde dann so lauten:
<img src="/fs4preview/preview/671041/file/fontimage/XQ8uxgDsSuVKFT3i4yEahQ.jpg" width="85" height="16" />