The Font function can be used to generate a graphic from a text in a true type font (.ttf). Any user-specific font stored on the server can be used for this.

The function is intended for use with graphic navigations, headings, etc.

Unlike the instruction function font (cf. instruction $CMS_VALUE(font(...))$) graphics with multi-row texts can be created.

The Font function delivers a return object which uses a $CMS_VALUE(...)$ instruction to deliver information on the generated picture.

The output of the picture with the desired text takes place using <img src=$CMS_REF(...)$.

"Font" function syntax

The basic structure of the Font function is as follows:

<CMS_FUNCTION name="Font" resultname="IDENTIFIER">
  <CMS_PARAM name="alpha" value="VALUE" />
  <CMS_PARAM name="boxjustify" value="KEYWORD" />
  <CMS_PARAM name="boxvalign" value="KEYWORD" />
  <CMS_PARAM name="color" value="COLOUR" />
  <CMS_PARAM name="filetype" value="KEYWORD" />
  <CMS_PARAM name="font" value="IDENTIFIER" />
  <CMS_PARAM name="justify" value="KEYWORD" />
  <CMS_PARAM name="lineheight" value="VALUE" />
  <CMS_PARAM name="media" value="IDENTIFIER" />
  <CMS_PARAM name="resolution" value="IDENTIFIER" />
  <CMS_PARAM name="size" value="VALUE" />
  <CMS_PARAM name="style" value="KEYWORD" />
  <CMS_PARAM name="width" value="VALUE" />
  <CMS_PARAM name="xoffset" value="VALUE" />
  <CMS_PARAM name="yoffset" value="VALUE" />
  <CMS_CDATA_PARAM name="text"><![CDATA[VALUE]]></CMS_CDATA_PARAM>
  ...
  <CMS_VALUE_PARAM name="text" value="IDENTIFIER" />
</CMS_FUNCTION>

For common notes about the syntax of header functions please see introducing Functions page.

Schematic representation

Schematic representation of the effect of the parameters

Font function parameters (overview)

The Font function can be specified with the following parameters:

Attribute	Meaning	possible values	Mandatory parameter
alpha	Degree of cover of the text	Integer	no
boxjustify	Horizontal alignment of a text area	left, center, right	no
boxvalign	Vertical alignment of a text area	top, center, bottom	no
color	Font color	Color value in hexadecimal notation	no
filetype	File type of the generated picture	jpg, png	no
font	Type font	Identifier	yes
justify	Horizontal text alignment	left, center, right	no
lineheight	Line height	Integer	no
media	Background picture; determines the width and height of the picture area	Identifier	yes
size	Font size	Integer	no
style	Font style	Keywords	Font-dependent
text	Text to be displayed	Characters	yes
width	Width of a text area	Integer	yes
xoffset	Horizontal shift of a text area	Integer	no
yoffset	Vertical shift of a text area	Integer	no

The parameters font, media, text and width are mandatory parameters.
In addition it must be noted that the parameters font, media and width must be defined at least once before using the text parameter for the first time.
The parameter style depends on the font type used. Whether it is a mandatory parameter or not depends on the font type selected.
All other parameters are optional parameters.

Mandatory parameters

font parameter

The font parameter is used to specify which font type is used for rendering the text. The parameter value must be given as the symbolic identifier (reference name) of a True Type Font (abbreviation: TTF, True Type Font) stored on the FirstSpirit server.

If no identifier or valid identifier is given an error is output during the preview and generation.

Fonts are created on the FirstSpirit server using ServerManager. The individual steps are described in the Installed fonts (→Documentation for Administrators).

This parameter must be specified before the first invocation of a text parameter!

<CMS_FUNCTION name="Font" resultname="name">
 <CMS_PARAM name="font" value="IDENTIFIER" />
 ...
 <CMS_CDATA_PARAM name="text"><![CDATA[...]]></CMS_CDATA_PARAM>
 ...
</CMS_FUNCTION>

width parameter

The width parameter is used to specify the width of a text area (see Schematic representation). The width of a text area is specified in pixels and should be less than the width of the picture area or the background picture.

If the text to be displayed is wider than the value given for the text area the text is automatically broken or wrapped. The last space before the specified width of the text area is exceeded is decisive for the wrapping. The wrapping occurs after this space.

Here is an example:

<CMS_FUNCTION name="Font" resultname="font">
  <CMS_PARAM name="width" value="120" />
  <CMS_PARAM name="size" value="14" />
  <CMS_PARAM name="media" value="background" />
  <CMS_PARAM name="color" value="#000000" />
  <CMS_PARAM name="boxjustify" value="center" />
  <CMS_PARAM name="justify" value="left" />
  <CMS_PARAM name="font" value="arial" />
  <CMS_CDATA_PARAM name="text"><![CDATA[Dies ist ein Beispielsatz für einen Textbereich]]></CMS_CDATA_PARAM>
</CMS_FUNCTION>

The text given in the example requires more space than 120 pixels. The 120 pixels are exceeded for the first time with the word Beispielsatz and then with the word einen. The text is therefore displayed with two wraps/breaks:

This parameter must be specified before the first invocation of a text parameter!

media parameter

The media parameter is used to specify the background picture on which the text areas are rendered. The background picture therefore specifies the width and height of the picture generated by means of the Font function.

The parameter expects the reference name of a picture from the Media Store as a value. The reference name does not have to be preceded by a media: :

<CMS_FUNCTION name="Font" resultname="name">
  <CMS_PARAM name="media" value="IDENTIFIER" />
  ...
  <CMS_CDATA_PARAM name="text"><![CDATA[...]]></CMS_CDATA_PARAM>
  ...
</CMS_FUNCTION>

This parameter must be specified before the first invocation of a text parameter!

If the picture from the Media Store is a transparent GIF or PNG picture the generated picture is also a transparent PNG picture. Otherwise a picture with a black background is generated.

If the background pictures are transparent the Font function does not render any texts!

text parameter

The text parameter is used to specify the content of a text area. The content can be specified either with the help of expressions or as the definition of a template fragment (comparable with a section template).

A picture generated by the Font function can contain several text areas.

Definition using expressions:

<CMS_FUNCTION name="Font" resultname="IDENTIFIER">
  <CMS_PARAM name="font" value="IDENTIFIER" />
  <CMS_PARAM name="media" value="IDENTIFIER" />
  <CMS_PARAM name="width" value="VALUE" />
  ...
  <CMS_VALUE_PARAM name="text" value="EXPRESSION" />
  ...
</CMS_FUNCTION>

Definition of a template fragment (comparable with a section template):

<CMS_FUNCTION name="Font" resultname="IDENTIFIER">
  <CMS_PARAM name="font" value="IDENTIFIER" />
  <CMS_PARAM name="media" value="IDENTIFIER" />
  <CMS_PARAM name="width" value="VALUE" />
  ...
  <CMS_CDATA_PARAM name="text">
    <![CDATA[
      BODY OF THE TEMPLATE FRAGMENT
    ]]>
  </CMS_CDATA_PARAM>
  ...
</CMS_FUNCTION>

The last value of a parameter is used for the generation of a text area:

<CMS_FUNCTION name="Font" resultname="schriftzug">
  <CMS_PARAM name="font" value="arial" />
  <CMS_PARAM name="media" value="wiese" />
  <CMS_PARAM name="width" value="150" />
  <CMS_PARAM name="size" value="12" />
  <CMS_CDATA_PARAM name="text">
    <![CDATA[
      1st Text area
    ]]>
  </CMS_CDATA_PARAM>
  <CMS_PARAM name="width" value="100" />
  <CMS_PARAM name="size" value="14" />
  <CMS_CDATA_PARAM name="text">
    <![CDATA[
      2nd Text area
    ]]>
  </CMS_CDATA_PARAM>
</CMS_FUNCTION>

In the example the parameters font, media, width and size are used for the text area 1st Text area used with the values arial, wiese, 150 and 12 .

For the text area 2nd Text area the same parameters are used but with the values arial, wiese, 100 and 14.

Optional parameters

filetype parameter

A picture generated by the Font function is as a default a PNG file (Portable Network Graphics). The parameter value for manual specification is: png.

The filetype parameter can be used to create a JPEG file (JPEG = Joint Photographic Experts Group) instead of a PNG file (Value: jpg).

<CMS_FUNCTION name="Font" resultname="name">
  <CMS_PARAM name="filetype" value="png" />
  ...
</CMS_FUNCTION>

<CMS_FUNCTION name="Font" resultname="name">
  <CMS_PARAM name="filetype" value="jpg" />
  ...
</CMS_FUNCTION>

size parameter

The size parameter can be used to specify the font size in points (symbol: pt) of a text area. If the parameter is not given the text area is formatted with the font size 14 points.

<CMS_FUNCTION name="Font" resultname="name">
  <CMS_PARAM name="size" value="INTEGER" />
  ...
</CMS_FUNCTION>

color parameter

The color parameter can be used to specify the font color for a text area. It is specified in six-figure hexadecimal notation with a preceding # (e.g. #123456). If the parameter is not given the text area is formatted with black font color (#000000).

<CMS_FUNCTION name="Font" resultname="name">
  <CMS_PARAM name="color" value="COLOR" />
  ...
</CMS_FUNCTION>

alpha parameter

The alpha parameter is used to specify the covering capacity (opacity) of a text area in percent. If the value is specified with 100 (default setting), the lettering of the text area is completely opaque. If a value <100 is specified the text area in front of the background picture becomes more transparent until a value of 0 where it is completely transparent (i.e. is no longer visible).

<CMS_FUNCTION name="Font" resultname="name">
  <CMS_PARAM name="alpha" value="INTEGER" />
  ...
</CMS_FUNCTION>

Specifying 0 results in completely transparent lettering and therefore it is no longer visible!

lineheight parameter

The lineheight parameter is used to specify the line height of a row (in a text area) in points (units: pt). The default value for this parameter is twice the value of the size parameter.

If a value is given which is less than the defined size value the individual text rows overlap.

<CMS_FUNCTION name="Font" resultname="name">
  <CMS_PARAM name="lineheight" value="INTEGER" />
  ...
</CMS_FUNCTION>

style parameter

Several font types support the specification of a special font style. The style parameter can be used to specify the individual font styles.

Several commonly used font styles are: italic and bold.

<CMS_FUNCTION name="Font" resultname="name">
  <CMS_PARAM name="style" value="KEYWORD" />
  ...
</CMS_FUNCTION>

boxjustify parameter

The boxjustify parameter is used to specify the horizontal alignment of a text area on the background graphic. The alignment only affects the text area and not the content (see also: Schematic representation).

The width of a text area results from the specification of the width parameter and the text content (parameter: text).

Valid values are: left (left-aligned = default), center (centered) and right (right-aligned).

<CMS_FUNCTION name="Font" resultname="name">
  <CMS_PARAM name="boxjustify" value="KEYWORD" />
  ...
</CMS_FUNCTION>

boxvalign parameter

The boxvalign parameter is used to specify the vertical alignment of a text area on the background graphic. The alignment only affects the text area and not the content (see also: Schematic representation).

The width of a text area results from the specification of the width parameter and the text content (parameter: text).

Valid values are: top (= default), center and right (bottom).

<CMS_FUNCTION name="Font" resultname="name">
  <CMS_PARAM name="boxvalign" value="KEYWORD" />
  ...
</CMS_FUNCTION>

justify parameter

The justify parameter is used to specify the horizontal alignment (justification) of text area content. The alignment only affects the content and not the text area (see also: Schematic representation).

The width of a text area results from the specification of the width parameter and the text content (parameter: text).

Valid values are: left (left-aligned = default), center (centred) and right (right-aligned).

<CMS_FUNCTION name="Font" resultname="name">
  <CMS_PARAM name="justify" value="KEYWORD" />
  ...
</CMS_FUNCTION>

xoffset parameter

The xoffset parameter can be used to horizontally move a text area on the background graphic.

The parameter expects an integer value. If the value is a negative integer the text area is moved to the left and if it is a positive integer the area is moved to the right.

<CMS_FUNCTION name="Font" resultname="name">
  <CMS_PARAM name="xoffset" value="INTEGER" />
  ...
</CMS_FUNCTION>

yoffset parameter

The yoffset parameter enables a text area to be vertically moved on the background graphic.

The parameter expects an integer value. If the value is a negative integer the text area is moved upwards and if it is a positive integer the area is moved downwards.

<CMS_FUNCTION name="Font" resultname="name">
  <CMS_PARAM name="yoffset" value="INTEGER" />
  ...
</CMS_FUNCTION>

Return object of the function

The return object of the Font functions can be used to determine information on the generated picture (e.g. width and height) with methods. The name of the object is the identifier assigned in resultname.

The following attributes can be accessed on the return object of the Font function:

Attribute	Description
IDENTIFIER.height	Returns the height of the generated picture in pixels.
IDENTIFIER.width	Returns the width of the generated picture in pixels.

For example:

Width of the image: $CMS_VALUE(font.width)$

The following syntax can be used for outputting the picture with the text which is specified via the parameter text:

<img src="$CMS_REF(font)$"/>

Examples of the Font function

Several examples of use of the instruction within templates are shown in the following. The examples are intended to clearly show the specific effect of the instruction and provide help for the template developer when creating their own templates.

The examples displayed here must be adjusted for use within a project! For example, variable names must be changed to the specific variable names of the project in which the instruction is to be used.

1st Example: A text area with automatic line break

<CMS_FUNCTION name="Font" resultname="font">
  <CMS_PARAM name="width" value="120" />
  <CMS_PARAM name="size" value="14" />
  <CMS_PARAM name="media" value="background" />
  <CMS_PARAM name="color" value="#000000" />
  <CMS_PARAM name="boxjustify" value="center" />
  <CMS_PARAM name="justify" value="left" />
  <CMS_PARAM name="font" value="arial" />
  <CMS_CDATA_PARAM name="text"><![CDATA[Dies ist ein Beispielsatz für einen Textbereich]]></CMS_CDATA_PARAM>
</CMS_FUNCTION>

In the example a text area with a width of 120 pixels is defined.
The background used is the picture with the reference name background .
The font size is defined as 14 points.
The font with the reference name arial is to be used.
The font color is to be black (#000000).
The text area is to be centre aligned, the content of the text area left-aligned.

The text is output as follows:

Dies ist ein 
Beispielsatz für 
einen Textbereich

2nd Example: Absolute positioning of text areas

<CMS_FUNCTION name="Font" resultname="font">
  <CMS_PARAM name="width" value="120" />
  <CMS_PARAM name="font" value="arial" />
  <CMS_PARAM name="size" value="12" />
  <CMS_PARAM name="media" value="background" />
  <CMS_PARAM name="color" value="#000000" />
  <CMS_PARAM name="xoffset" value="5" />
  <CMS_PARAM name="yoffset" value="5" />
  <CMS_CDATA_PARAM name="text"><![CDATA[Dies]]></CMS_CDATA_PARAM>
  <CMS_PARAM name="size" value="12" />
  <CMS_PARAM name="color" value="#999999" />
  <CMS_PARAM name="xoffset" value="15" />
  <CMS_PARAM name="yoffset" value="15" />
  <CMS_CDATA_PARAM name="text"><![CDATA[ist]]></CMS_CDATA_PARAM>
  <CMS_PARAM name="size" value="12" />
  <CMS_PARAM name="color" value="#666666" />
  <CMS_PARAM name="xoffset" value="25" />
  <CMS_PARAM name="yoffset" value="25" />
  <CMS_CDATA_PARAM name="text"><![CDATA[ein]]></CMS_CDATA_PARAM>
  <CMS_PARAM name="size" value="12" />
  <CMS_PARAM name="color" value="#000000" />
  <CMS_PARAM name="xoffset" value="35" />
  <CMS_PARAM name="yoffset" value="35" />
  <CMS_CDATA_PARAM name="text"><![CDATA[Beispielsatz.]]></CMS_CDATA_PARAM>
</CMS_FUNCTION>

In the example the sentence "Dies ist ein Beispielsatz." is defined in stepped form.

Each individual word is to be displayed with each word growing with a horizontal and vertical offset of 10 pixels. The calculation is to be carried out absolutely from the top left-hand corner of the background graphic.

The result is as follows:

3rd Example: Output of width and height

Definition of the Font function

<CMS_FUNCTION name="Font" resultname="font">
  <CMS_PARAM name="width" value="120" />
  <CMS_PARAM name="size" value="14" />
  <CMS_PARAM name="media" value="background" />
  <CMS_PARAM name="color" value="#000000" />
  <CMS_PARAM name="boxjustify" value="center" />
  <CMS_PARAM name="justify" value="left" />
  <CMS_PARAM name="font" value="arial" />
  <CMS_CDATA_PARAM name="text"><![CDATA[Dies ist ein Beispielsatz für einen Textbereich]]></CMS_CDATA_PARAM>
</CMS_FUNCTION>

Invoke the Font function using the width and height:

$CMS_SET(set_font, font)$

<img src="$CMS_REF(set_font)$" width="$CMS_VALUE(set_font.width)$" height="$CMS_VALUE(set_font.height)$">

The example outputs the generated picture (see 1st Example). The dimensions of the picture are determined for the HTML attributes width and height.

An exemplary output is:

<img src="/fs4preview/preview/671041/file/fontimage/bPQfrNllCZXXycTcCpNZ7w.png" width="254" height="219">

Print version | Page start