Start page / Template development / Template syntax / Functions / in the header / Font

Font

Contents

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>
Important 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

    
Important 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).

Important 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:

Important 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>

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

Important 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.
Important 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>

Important 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>

Important 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.

Important 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">

© 2005 - 2024 Crownpeak Technology GmbH | All rights reserved. | FirstSpirit 2024.10 | Data privacy