font(...)

The font(...) function can be used to render a text as a graphic, optionally with a background graphic too.

The parameters of the font(...) function are similar to the parameters of the Font function.

Unlike the Font function the font(...) function can only be used to display a text area.

The font(...) function can be used within a $CMS_REF(...)$ or $CMS_VALUE(...)$ instruction.

The font(...) function returns a return object which with a $CMS_VALUE(...)$ instruction returns information on the generated picture.

Syntax of the font(...) function

The basic structure of the font(...) function is as follows:

$CMS_REF(
  font(
    alpha:VALUE,
    bounds:"KEYWORD",
    boxjustify:"KEYWORD",
    boxvalign:"KEYWORD",
    color:"COLOR",
    filetype:"KEYWORD",
    fractionalmetrics:BOOLEAN_VALUE,
    font:"IDENTIFIER",
    height:VALUE,
    justify:"KEYWORD",
    lineheight:VALUE,
    media:"IDENTIFIER",
    resolution:"IDENTIFIER",
    size:VALUE,
    style:"KEYWORD",
    text_antialiasing:BOOLEAN_VALUE,
    width:VALUE,
    xoffset:VALUE,
    yoffset:VALUE,
    text:OBJECT
  )
)$

Schematic representation

Schematic representation of the effect of the parameters

Font(...) function parameters

The font(...) function can be specified with the following 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 the parameter is not given the internal Sun font SansSerif is used.

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

$CMS_REF(
 font(
 font:"IDENTIFIER",
 ...
 text:"..."
 )
)$

height parameter

The height parameter is used to specify the height of a text area (see Schematic representation). The height of the text area is given in pixels.

Unlike the Font function the text area is identical to the picture area, i.e. the given height corresponds to the height of the generated picture.

There is no automatic break in text (text wrapping).

The width parameter only has an effect with the height parameter.

If the media parameter is specified, neither width nor height has an effect.

$CMS_REF(
  font(
    height:VALUE,
    width:VALUE,
    ...
    text:"..."
  )
)$

width parameter

The width parameter is used to specify the width of a text area (see Schematic representation). The width of the text area is given in pixels.

Unlike the Font function the text area is identical to the picture area, i.e. the given width corresponds to the width of the generated picture.

There is no automatic break in text (text wrapping).

The width parameter only has an effect with the height parameter.

If the media parameter is specified, neither width nor height has an effect.

$CMS_REF(
  font(
    height:VALUE,
    width:VALUE,
    ...
    text:"..."
  )
)$

media parameter

The media parameter is used to specify the background picture on which the text area is rendered. The background picture does not specify the width and height of the generated picture. To copy the width and height of the generated picture from the background picture the bounds parameter must be used.

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_REF(
  font(
    media:"IDENTIFIER",
    ...
    text:"..."
  )
)$

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.

text parameter

The text parameter is used to specify the content of the 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 only contain one text area.

The parameter must be specified as the last parameter of the font(...) function.

Definition using expressions:

$CMS_REF(
    ...
    text:EXPRESSION
  )
)$

Definition using constants:

$CMS_REF(
    ...
    text:"CONSTANT"
  )
)$

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 specify a

• JPEG file (JPG = Joint Photographic Experts Group, value: jpg)
• WebP file (value: webp)

instead of a PNG file.
Examples:

$CMS_REF(
  font(
    filetype:"png",
  ...
    text:"..."
  )
)$

$CMS_REF(
  font(
    filetype:"jpg",
  ...
    text:"..."
  )
)$

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

$CMS_REF(
  font(
    size:INTEGER,
    ...
    text:""
  )
)$

bounds parameter

This parameter can be used to adjust the size of the generated picture to the background graphic.

In order for the generated picture to correspond to the size of the background graphic the keyword image must be specified.

$CMS_REF(
  font(
    media:"IDENTIFIER",
    bounds:"image",
    ...
    text:""
  )
)$

The parameter is only used if the media parameter has been specified too.

If the parameter has not been specified the generated picture has the width and height of the text area, unless the height and width parameters were specified.

text_antialiasing parameter

The text_antialiasing parameter can be used to deactivate default text smoothing (anti-aliasing).

To deactivate the text smoothing, text_antialiasing must be specified with the Boolean value false.

$CMS_REF(
  font(
    text_antialiasing:false,
    ...
    text:""
  )
)$

fractionalmetrics parameter

If text smoothing is deactivated (see text_antialiasing parameter) in the case of smaller font sizes the letters can be pushed into each other or displayed as overlaid or superimposed letters.

This effect can be prevented using the fractionalmetrics parameter. In order for letters not to be pushed into each other or superimposed the parameter must be specified with the Boolean value false.

If the parameter is not given the letters are pushed into each other or are displayed superimposed.

$CMS_REF(
  font(
    text_antialiasing:false,
    fractionalmetrics:false,
    ...
    text:""
  )
)$

bgcolor parameter

The bgcolor parameter can be used to specify the background colour for the picture area. It is specified in six-figure hexadecimal notation with a preceding # (e.g. #123456). If the parameter is not given the picture area is generated with white background colour (#FFFFFF).

$CMS_REF(
  font(
    bgcolor:"COLOUR",
    ...
    text:""
  )
)$

color parameter

The color parameter can be used to specify the font color for the 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 generated with black font color (#000000).

$CMS_REF(
  font(
    color:"COLOR",
    ...
    text:""
  )
)$

alpha parameter

The alpha parameter is used to specify the covering capacity (opacity) of the 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_REF(
  font(
    alpha:INTEGER,
    ...
    text:""
  )
)$

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 the text area) in points (units: pt). The default value for this parameter is twice the value of the size parameter.

$CMS_REF(
  font(
    lineheight:INTEGER,
    ...
    text:""
  )
)$

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_REF(
  font(
    style:"KEYWORD",
    ...
    text:""
  )
)$

boxjustify parameter

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

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

$CMS_REF(
  font(
    boxjustify:"KEYWORD",
    ...
    text:""
  )
)$

boxvalign parameter

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

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

$CMS_REF(
  font(
    boxvalign:"KEYWORD",
    ...
    text:""
  )
)$

justify parameter

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

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

$CMS_REF(
  font(
    justify:"KEYWORD",
    ...
    text:""
  )
)$

xoffset parameter

The xoffset parameter can be used to horizontally move the 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_REF(
  font(
    xoffset:INTEGER,
    ...
    text:""
  )
)$

yoffset parameter

The yoffset parameter can be used to vertically move the text area 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_REF(
  font(
    yoffset:INTEGER,
    ...
    text:""
  )
)$

Return object

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 methods can either be applied directly on the font(...) invocation:

$CMS_VALUE(font(...).width)$

or in conjunction with a $CMS_SET(...)$ instruction:

$CMS_SET(IDENTIFIER, font(...))$
$CMS_VALUE(IDENTIFIER.width)$

The following attributes can be accessed on the return object of the font(...) function:

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 template developers 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.

<img src="$CMS_REF(
  font(
      font:"Arial",
      size:14,
      filetype:"jpg",
      color:"#FF0000",
      text:"Schnäppchen"
  )
)$" />

In the example the font Arial, with font size 14 and in red is used to generate a JPG picture with the text Schnäppchen.

The generated picture is as follows:

In addition the generation of the picture can be combined with the output of the width and height:

$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)$" />

An exemplary output would then be:

<img src="/fs4preview/preview/671041/file/fontimage/XQ8uxgDsSuVKFT3i4yEahQ.jpg" width="85" height="16" />