Data types

The values assigned to properties in TypoScript are often of a specific format. These formats are described in this chapter.

For example, if a value is defined as the type <tag>, HTML code has to be supplied. If it is of the type resource, it's a reference to a file from the resource-field in the template. If the type is GraphicColor, a color-definition is expected and an HTML color code or comma-separated RGB-values have to be provided.

The following is a list of available data types, their usage, purpose and examples.

align

Data type:
align
Description:
Decides about alignment.
Examples:
left, center, right
Default:
left

boolean

Data type:
boolean
Description:

Possible values for boolean variables are 1 and 0 meaning TRUE and FALSE.

Everything else is evaluated to one of these values by PHP: Non-empty strings (except 0 [zero]) are treated as TRUE, empty strings are evaluated to FALSE.

Examples:
dummy.enable = 0   # false, preferred notation
dummy.enable = 1   # true,  preferred notation
dummy.enable =     # false, because the value is empty

case

Data type:
case
Description:
Do a case conversion.
Possible values:
Value Effect
upper Convert all letters of the string to upper case
lower Convert all letters of the string to lower case
capitalize Uppercase the first character of each word in the string
ucfirst Convert the first letter of the string to upper case
lcfirst Convert the first letter of the string to lower case
uppercamelcase Convert underscored upper_camel_case to UpperCamelCase
lowercamelcase Convert underscored lower_camel_case to lowerCamelCase
Example:

Code:

10 = TEXT
10.value = Hello world!
10.case = upper

Result:

HELLO WORLD!

Object types

These are complex "data types" which contain several member variables. The following types are descerned according to their internal processing:

cObject

Data type:
cObject
Description:
"cObjects" are also called "Content Objects". See the section "Content Objects".
Examples:
TEXT / IMAGE / TEMPLATE ...

frameObj

Data type:
FRAMESET / FRAME

Gifbuilder Object

Description:
See section GIFBUILDER in this manual.
Examples:
TEXT / SHADOW / OUTLINE / EMBOSS / BOX / IMAGE / EFFECT

date-conf

Data type:
date-conf
Description:

Used to format a date, see PHP function date(). The following abbreviations are available:

Abb The abbreviation is expanded to:
a "am" or "pm"
A "AM" or "PM"
d 01 - 31, day of the month, numeric, 2 digits with leading zeros
D day of the week, textual, 3 letters like "Fri"
F month, textual, long, like "January"
h hour, numeric, 12 hour format
H hour, numeric, 24 hour format
i minutes, numeric
j 1 - 31, day of the month, numeric, without leading zeros
l (lowercase 'L'), day of the week, textual, long, like "Friday"
m month, numeric
M month, textual, 3 letters, like "Jan"
s seconds, numeric
S English ordinal suffix, textual, 2 characters, like "th" or "nd"
U seconds since the epoch
Y year, numeric, 4 digits, like "2013"
w day of the week, numeric, 0 represents Sunday
y year, numeric, 2 digits, like "13"
z day of the year, numeric, like "299"
Example:
d-m-y

degree

Data type:
degree
Description:
-90 to 90, integers
Example:
45

dir

Data type:
dir
Syntax:
[path relative to the web root of the site] | [list of valid extensions] | [sorting: name, size, ext, date] | [reverse: "r"] | [return full path: boolean]
Description:
Files matching are returned in a comma-separated string.
Example:

This example returns a list of all pdf, gif and jpg-files from fileadmin/files/ sorted by their name reversely and with the full path (with fileadmin/files/ prepended):

fileadmin/files/ | pdf,gif,jpg | name | r | true

function name

Data type:
function name
Description:

Indicates a function or method in a class to call. See more information at the USER cObject.

If no namespaces are used, then the class or function name, but not the method name, should probably be prefixed with user_. The prefix can be changed in the $GLOBALS['TYPO3_CONF_VARS'] config though. The function / method is normally called with 2 parameters, $conf which is the TypoScript configuration and $content, some content to be processed and returned.

If no namespaces are used and if a method in a class is called, it is checked (when using the USER/USER_INT objects) whether a class with the same name, but prefixed with ux_ is present and if so, this class is instantiated instead. See the document "Inside TYPO3" for more information on extending classes in TYPO3!

Examples:

Method in namespaced class. This is the preferred version:

Your\NameSpace\YourClass->reverseString

Single Function:

user_reverseString

Method in class without namespace:

user_yourClass->reverseString

getText

Data type:
getText
Description:

The getText data type is some kind of tool box allowing to retrieve values from a variety of sources, e.g. from GET/POST variables, from registers, values from the page tree, items in the page menus, records from any database table, etc.

The general syntax is as follows:

key : code

where key indicates the source and code is some form of path or pointer to the value, which depends on the key used. The various keys and their possible codes are described below.

The code can contain pipe characters | to separate keys in a multi-dimensional array. This e.g. works with TSFE:

foo = TSFE : fe_user|user|username

Some codes work with different separator, which is documented right at the code. Spaces around the colon (:) are irrelevant. The key is case-insensitive.

By separating the value of getText with // (double slash) a number of codes can be supplied and getText will return the first one, which is not empty ("" or zero).

To get the content of the field "header". If "header is empty, "title" is retrieved. If "title" is empty as well, it finally gets the field "uid":

foo = field : header // field : title // field : uid

cObj

getText Key:
cObj
Description:

For CONTENT and RECORDS cObjects that are returned by a select query, this returns the row number (1,2,3,...) of the current cObject record.

parentRecordNumber is the only key available.

Example:

Get the number of the current cObject record:

foo = cObj : parentRecordNumber

context

getText Key:
context
Description:

access values from context API (see). If a property is an array, it is converted into a comma-separated list.

Syntax:

data = context:[aspectName]:[propertyName]
Example:

Retrieve current workspace id:

page.10 = TEXT
page.10.data = context:workspace:id
page.10.wrap = You are in workspace: |

current

getText Key:
current
Description:
current (gets the "current" value)
Example:

Get the current value:

foo = current

date

getText Key:
date
Description:
Can be used with a colon and date-conf.
Default:
d/m Y
Example:

Get the current time formatted dd-mm-yy:

foo = date : d-m-y

DB

getText Key:
DB
Syntax:
DB : [table name] : [uid] : [field]
Description:

Value from database. Any record from a table in TCA can be selected here. Records marked as deleted will not return any value.

In contrast to other keys, colons are used here to get deeper into the structure, instead of pipes.

Example:

Get the value of the header field of record with uid 234 from table "tt_content":

foo = DB : tt_content:234:header

debug

getText Key:
debug
Description:
Returns HTML-formatted content of the PHP variable defined by the keyword. Available keywords are rootLine, fullRootLine, data, register and page.
Example:

Outputs the current root-line visually in HTML:

foo = debug : rootLine

field

getText Key:
field
Syntax:
field : [field name from the current $cObj->data array in the cObject, multi-dimensional.]
Description:

This gives read access to the current value of an internal global variable determined by the given key.

  • As default the $cObj->data array is $GLOBALS['TSFE']->page (record of the current page)
  • In TMENU $cObj->data is set in a loop to the page-record for each menu item during its rendering process.
  • In CONTENT / RECORDS $cObj->data is set to the actual record
  • In GIFBUILDER $cObj->data is set to the data GIFBUILDER is supplied with.
Examples:

Get content from $cObj->data['header']:

foo = field : header

Get content from $cObj->data['fieldname']['level1']['level2']:

foo = field : fieldname|level1|level2

file

getText Key:
file
Syntax:
file : [uid] : [property]
Description:

Retrieves a property from a file object (FAL) by identifying it through its sys_file UID. Note that during execution of the FILES cObject, it's also possible to reference the current file with "current" as UID like file : current : size.

The following properties are available: name, uid, originalUid, size, sha1, extension, mimetype, contents, publicUrl, modification_date, creation_date

Furthermore when manipulating references (such as images in content elements or media in pages), additional properties are available (not all are available all the time, it depends on the setup of references of the FILES cObject): title, description, link, alternative.

Additionally, any data in the "sys_file_metadata" table can be accessed too.

See the FILES cObject for usage examples.

Example:

Get the file size of the file with the sys_file UID 17:

foo = file : 17 : size

flexform

getText Key:
flexform
Syntax:
flexform : [field containing flexform data].[property of this flexform]
Description:
Access values from flexforms, e.g. inside of tt_content record. In contrast to most parts, deeper levels are accessed through dots, not pipes.
Example:

Return the flexform value of given name:

foo = flexform : pi_flexform:settings.categories

fullRootLine

getText Key:
fullRootLine
Syntax:
fullRootLine : [pointer, integer], [field name], ["slide"]
Description:

This property can be used to retrieve values from "above" the current page's root. Take the below page tree and assume that we are on the page "Here you are!". Using the levelfield property, it is possible to go up only to the page "Site root", because it is the root of a new (sub-)site. With fullRootLine it is possible to go all the way up to page tree root. The numbers between square brackets indicate to which page each value of pointer would point to:

- Page tree root [-2]
|- 1. page before [-1]
   |- Site root (root template here!) [0]
   |- Here you are! [1]

A "slide" parameter can be added just as for the levelfield property.

Example:

Get the title of the page right before the start of the current website:

foo = fullRootLine : -1, title

getenv

getText Key:
getenv
Description:

Value from PHP environment variables.

For a cached variation of this feature, please refer to getEnv.

Example:

Get the env var HTTP_REFERER:

foo = getenv : HTTP_REFERER

getIndpEnv

getText Key:
getIndpEnv
Syntax:
getIndpEnv : <name>
Description:

Returns the value of a System Environment Variable denoted by name regardless of server OS, CGI/MODULE version etc. The result is identical to the $_SERVER variable in most cases. This method should be used instead of getEnv to get reliable values for all situations. The internal processing is handled by TYPO3\CMS\Core\Utility\GeneralUtility::getIndpEnv()

Available names:

Name Definition Example or result
_ARRAY Return an array with all available key-value pairs for debugging purposes  
HTTP_ACCEPT_LANGUAGE language(s) accepted by client  
HTTP_HOST [host][:[port]] 192.168.1.4:8080
HTTP_REFERER [scheme]://[host][:[port]][path] http://192.168.1.4:8080/typo3/32/temp/phpcheck/index.php/arg1/arg2/arg3/?arg1,arg2,arg3&p1=parameter1&p2[key]=value
HTTP_USER_AGENT client user agent  
PATH_INFO [path_info] /arg1/arg2/arg3/
QUERY_STRING [query] arg1,arg2,arg3&p1=parameter1&p2[key]=value
REMOTE_ADDR client IP  
REMOTE_HOST client host  
REQUEST_URI [path]?[query] /typo3/32/temp/phpcheck/index.php/arg1/arg2/arg3/?arg1,arg2,arg3&p1=parameter1&p2[key]=value
SCRIPT_FILENAME absolute filename of script  
SCRIPT_NAME [path_script] /typo3/32/temp/phpcheck/[index.php]
TYPO3_DOCUMENT_ROOT absolute path of root of documents  
TYPO3_HOST_ONLY [host] 192.168.1.4
TYPO3_PORT [port] 8080
TYPO3_REQUEST_DIR [scheme]://[host][:[port]][path_dir]  
TYPO3_REQUEST_HOST [scheme]://[host][:[port]]  
TYPO3_REQUEST_SCRIPT [scheme]://[host][:[port]][path_script]  
TYPO3_REQUEST_URL [scheme]://[host][:[port]][path]?[query]  
TYPO3_REV_PROXY TRUE if this session runs over a well known proxy  
TYPO3_SITE_SCRIPT [script / Speaking URL] of the TYPO3 website  
TYPO3_SITE_URL [scheme]://[host][:[port]][path_dir] of the TYPO3 website frontend  
TYPO3_SSL TRUE if this session uses SSL/TLS (https)  
Examples:
# get and output the client IP
page = PAGE
page.10 = TEXT
page.10.stdWrap.data = getIndpEnv : REMOTE_ADDR
page.10.stdWrap.htmlSpecialChars = 1

global

getText Key:
global
Syntax:
global : [variable]
Description:
Deprecated, use GP, TSFE or getenv.

GP

getText Key:
GP
Syntax:
GP : [Value from GET or POST method]
Description:
Get an variable from $_GET or $_POST where a variable, which exists in both arrays, is returned from $_POST.
Examples:

Get input value from query string &stuff=...:

foo = GP : stuff

Get input value from query string &stuff[bar]=...:

foo = GP : stuff|bar

level

getText Key:
level
Description:
Get the root line level of the current page.
Example:

Get the root line level of the current page:

foo = level

levelfield

getText Key:
levelfield
Syntax:
levelfield : [pointer, integer], [field name], ["slide"]
Description:
levelfield: Like leveltitle, leveluid, levelmedia et al. but where the second parameter is the root line field to fetch.
Example:

Get the value of the user defined field user_myExtField in the root line. Requires additional configuration in $GLOBALS['TYPO3_CONF_VARS']['FE']['addRootLineFields'] to include field.:

foo = levelfield : -1, user_myExtField, slide

leveltitle, leveluid, levelmedia

getText Key:
leveltitle, leveluid or levelmedia
Syntax:
leveltitle, leveluid, levelmedia: [levelTitle, uid or media in root line, 0- , negative = from behind, " , slide" parameter forces a walk to the bottom of the root line until there's a "true" value to return. Useful with levelmedia.]
Description:
Returns values from up or down the page tree.
Examples:

Get the title of the page on the first level of the root line:

foo = leveltitle : 1

Get the title of the page on the level right below the current page AND if that is not present, walk to the bottom of the root line until there's a title:

foo = leveltitle : -2, slide

Get the id of the root-page of the website (level zero):

foo = leveluid : 0

LLL

getText Key:
LLL
Description:
LLL: Reference to a locallang (xlf, xml or php) label. Reference consists of [fileref]:[labelkey]
Example:

Get localized label for logout button:

foo = LLL : EXT:felogin/pi1/locallang.xlf:logout

page

getText Key:
page
Description:
page: [field in the current page record]
Example:

Get the current page title:

foo = page : title

pagelayout

getText Key:
pagelayout
Description:
pagelayout
Example:

Get the current backend layout:

foo = pagelayout

parameters

getText Key:
parameters
Syntax:
parameters: [field name from the current $cObj->parameters array in the cObject.]
Description:
See parseFunc.
Example:

Get content from $cObj->parameters['color']:

foo = parameters : color

path

getText Key:
path
Description:
Path to a file, possibly placed in an extension, returns empty if the file does not exist.
Example:

Get path to file rsaauth.js (inside extension rsaauth) relative to siteroot:

foo = path : EXT:rsaauth/resources/rsaauth.js

register

getText Key:
register
Syntax
register: [field name from the $GLOBALS['TSFE']->register]
Description:
See LOAD_REGISTER.
Example:

Get content from $GLOBALS['TSFE']->register['color']:

foo = register : color

session

getText Key:
session
Syntax:
session : [key]
Description:
The key refers to the session key used to store the value.
Example:

Get the number of items of a stored shopping cart array/object:

foo = session : shop_cart|itemCount

TSFE

getText Key:
TSFE
Syntax:
TSFE: [value from the $GLOBALS['TSFE'] array, multi-dimensional]
Description:
Returns a value from TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController.
Example:

Get the "username" field of the current FE user:

foo = TSFE : fe_user|user|username

GraphicColor

Data type:
GraphicColor
Syntax:

[colordef] : [modifier]

Where modifier can be an integer which is added or subtracted to the three RGB-channels or a floating point with an * before, which will then multiply the values with that factor.

Description:
The color can be given as HTML-color or as a comma-separated list of RGB-values (integers). An extra parameter can be given, that will modify the color mathematically:
Examples:

red (HTML-color)

#ffeecc (HTML-color)

255,0,255 (RGB-integers)

Extra:

red : *0.8 ("red" is darkened by factor 0.8)

#ffeecc : +16 ("ffeecc" is going to #fffedc because 16 is added)

HTML code

Data type:
HTML code
Description:
Pure HTML code
Example:
<b>Some text in bold</b>

HTML-color

Data type:
HTML-color
Description:

Named colors or color codes.

Some HTML color codes are:

Color name Hexadecimal code
Black #000000
Silver #C0C0C0
Gray #808080
White #FFFFFF
Maroon #800000
Red #FF0000
Purple #800080
Fuchsia #FF00FF
Green #008000
Lime #00FF00
Olive #808000
Yellow #FFFF00
Navy #000080
Blue #0000FF
Teal #008080
Aqua #00FFFF
Examples:

red

#ffeecc

imageExtension

Data type:
imageExtension
Description:

Image extensions can be anything among the allowed types defined in the global variable $GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext']. Standard is pdf, gif, jpg, jpeg, tif, bmp, ai, pcx, tga, png.

The value "web" is special. This will just ensure that an image is converted to a web image format (gif or jpg) if it happens not to be already!

Examples:

jpg

web (gif or jpg ..)

imgResource

Data type:
imgResource
Description:
  1. A resource plus imgResource properties.

    Filetypes can be anything among the allowed types defined in the configuration variable $GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext']. Standard is pdf, gif, jpg, jpeg, tif, bmp, ai, pcx, tga, png.

  2. A GIFBUILDER object. See the object reference for GIFBUILDER below.

Examples:

Here "file" is an imgResource:

10 = IMAGE
10 {
    file = fileadmin/toplogo.gif
    file.width = 200
}

GIFBUILDER:

10 = IMAGE
10.file = GIFBUILDER
10.file {
    # GIFBUILDER properties here...
}

integer

Data type:
integer / int
Examples:
42, -8, -9, 0
Description:
This data type is sometimes used generally though another type would have been more appropriate, like pixels.

linkWrap

Data type:
linkWrap
Syntax:
<.. {x}.> | </...>
Description:

{x}; x is an integer (0-9) and points to a key in the PHP array root line. The key is equal to the level the current page is on measured relatively to the root of the website.

If the key exists the uid of the level that key pointed to is inserted instead of {x}.

Thus we can insert page_ids from previous levels.

Example:

This will make a link to the root-level of a website:

<a href="?id={0}"> | </a>

list

Data type:
list
Description:
List of values, comma separated. Values are trimmed, leading whitespace is therefore ignored before and after each comma.
Example:
item,item2,item3

margins

Data type:
margins
Syntax:
left, top, right, bottom
Example:

This sets margin-left to 10 and margin-bottom to 5. Top and right are not set (zero):

10,0,0,5

page_id

Data type:
page_id
Description:
A page id (integer) or this (=current page id).
Examples:
this
34

path

Data type:
path
Description:
Path relative to the root directory from which we operate.
Example:
fileadmin/stuff/

pixels

Data type:
pixels
Description:
pixel-distance
Example:
345

positive integer

Data type:
positive integer / posint / int+
Description:
Positive integer.
Examples:
42, 8, 9

resource

Data type:
resource
Description:
If the value contains a "/", it is expected to be a reference (absolute or relative) to a file in the file system. There is no support for wildcard characters in the name of the reference.
Example:

Reference to a file in the file system:

fileadmin/picture.gif

rotation

Data type:
rotation
Description:
integer, degrees from 0 - 360
Example:
180

space

Data type:
space
Syntax:
"space before | space after"
Description:
Used for content and sets the according number of pixels space "before | after".
Example:
5 | 5

strftime-conf

Data type:
strftime-conf
Description:
Abb The abbreviation is expanded to:
%a abbreviated weekday name according to the current locale
%A full weekday name according to the current locale
%b abbreviated month name according to the current locale
%B full month name according to the current locale
%c preferred date and time representation for the current locale
%C century number (the year divided by 100 and truncated to an integer, range 00 to 99)
%d day of the month as a decimal number (range 00 to 31)
%D same as %m/%d/%y
%e day of the month as a decimal number, a single digit is preceded by a space (range ' 1' to '31'). Note that the %e modifier is not supported in the Windows implementation of 'strftime'.
%h same as %b
%H hour as a decimal number using a 24-hour clock (range 00 to 23)
%I hour as a decimal number using a 12-hour clock (range 01 to 12)
%j day of the year as a decimal number (range 001 to 366)
%m month as a decimal number (range 01 to 12)
%M minute as a decimal number
%n newline character
%p either `am' or `pm' according to the given time value, or the corresponding strings for the current locale
%r time in a.m. and p.m. notation
%R time in 24 hour notation
%S second as a decimal number
%t tab character
%T current time, equal to %H:%M:%S
%u weekday as a decimal number [1,7], with 1 representing Monday
%U week number of the current year as a decimal number, starting with the first Sunday as the first day of the first week
%V The ISO 8601:1988 week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the current year, and with Monday as the first day of the week.
%W week number of the current year as a decimal number, starting with the first Monday as the first day of the first week
%w day of the week as a decimal, Sunday being 0
%x preferred date representation for the current locale without the time
%X preferred time representation for the current locale without the date
%y year as a decimal number without a century (range 00 to 99)
%Y year as a decimal number including the century
%Z time zone or name or abbreviation
%% a literal `%' character
Examples:

Date "DD-MM-YY" =

%e:%m:%y

Time "HH:MM:SS" =

%H:%M:%S

or just

%T

string

Data type:
string / str / value
Description:
Sometimes used generally though another type would have been more appropriate, like "align".
Example:
The quick brown fox jumps over the lazy dog.

<tag>

Data type:
<tag>
Description:
An HTML tag.
Example:
<body lang="de">

<tag>-data

Data type:
<tag>-data
Examples:

<frameset>-data: row

could be '150,*'

<tag>-params

Data type:
<tag>-params
Description:
Parameters for a tag.
Example:

For <frameset>-params:

border="0" framespacing="0"

target

Data type:
target
Examples:
_top, _blank, content
Description:

Target in an <a>-tag.

This is normally the same value as the name of the root-level object that defines the frame.

UNIX-time

Data type:
UNIX-time
Description:
Seconds since January 1st 1970.
Example:

Seconds to May 09th 2016 12:34:

1462790096

VHalign

Data type:
VHalign
Description:

Pair of values separated by a comma. The first value determines the horizontal alignment, the second one the vertical alignment.

Possible values:

  • r/c/l
  • t/c/b

Horizontal values standing for: right, center, left

Vertical values standing for: top, center, bottom

Default:
l , t
Example:

Horizontal alignment = right and Vertical alignment = center:

r , c

wrap

Data type:
wrap
Syntax:
<...> | </...>
Description:

Used to wrap something. The vertical bar ("|") is the place, where your content will be inserted; the parts on the left and right of the vertical line are placed on the left and right side of the content.

Spaces between the wrap-parts and the divider ("|") are trimmed off from each part of the wrap.

If you want to use more sophisticated data functions, then you should use stdWrap.dataWrap instead of wrap.

A wrap is processed and rendered as the last of the other components of a cObject.

Example:

This will cause the value to be wrapped in a p-tag coloring the value red:

<p style="color: red;"> | </p>

x,y,w,h

Data type:
x,y,w,h
Description:

x,y is the offset from the upper left corner.

w,h is the width and height

Example:
10,10,5,5