Site settings definitions

New in version 13.1

Site-scoped setting definitions where introduced. They will most likely be the place to configure site-wide configuration, which was previously only possible to modify via modifying TypoScript constants, for example in the Constant Editor.

Site settings definitions allow to define settings with a type and a guaranteed default value. They can be defined in Site sets, in a file called settings.definitions.yaml.

It is recommended to use site-sets and their UI configuration in favor of TypoScript Constants.

All available settings are displayed in the Site settings editor.

The site settings provided by an extension can be automatically documented in the extensions manual, see site settings documentation.

Table of contents

Site setting definition example

        EXT:blog_example/Configuration/Sets/BlogExample/settings.definitions.yaml (Excerpt)
    

categories:
  BlogExample:
    label: 'Blog Example' # (1)
  BlogExample.templates:
    label: 'Templates' # (2)
    parent: BlogExample
  BlogExample.pages:
    label: 'Pages'
    parent: BlogExample

settings:
  blogExample.templateRootPath:  # (5)
    label: 'Templates' # (3)
    category: BlogExample.templates # (2)
    description: 'Path to template root'  # (4)
    type: string  # (6)
    default: 'EXT:blog_example/Resources/Private/Templates/'  # (7) + (8)
  blogExample.partialRootPath:
    label: 'Partials'
    category: BlogExample.templates
    description: 'Path to partial root'
    type: string
    default: 'EXT:blog_example/Resources/Private/Partials/'

See the complete example at settings.definitions.yaml (GitHub).

Screenshot demonstration the position of the categories, labels etc — The parts marked by a number can be configured, see list bellow

Site setting definition properties

Name	Type	Required
categories	array
label	string
parent	categories key
settings	array
label	string
description	string
category	categories key
type	a definition type	true
default	mixed	true
readonly	bool

categories

Type: array

label

Type: string

parent

Type: categories key

settings

Type: array

label

Type: string

description

Type: string

category

Type: categories key

type

Type: a definition type
Required: true

default

Type: mixed
Required: true

The default value must have the same type like defined in type.

readonly

Type: bool

If a site setting is marked as readonly, it can be overridden only by editing the config/sites/my-site/settings.yaml directly, but not from within the editor.

Definition types

Name	Type	Required
int	string
number	string
bool	string
string	string
text	string
stringlist	string
color	string

int

Type: string
Path: settings.[my_val].type = int

Checks whether the value is already an integer or can be interpreted as an integer. If yes, the string is converted into an integer.

number

Type: string
Path: settings.[my_val].type = number

Checks whether the value is already an integer or float or whether the string can be interpreted as an integer or float. If yes, the string is converted to an integer or float.

bool

Type: string
Path: settings.[my_val].type = bool

If the value is already a boolean, it is returned directly 1 to 1.

If the value is an integer, then false is returned for 0 and true for 1.

If the value is a string, the corresponding Boolean value is returned for true, false, yes, no, on, off, 0 and 1.

string

Type: string
Path: settings.[my_val].type = string

Converts almost all data types into a string. If an object has been specified, it must be stringable, otherwise no conversion takes place. Boolean values are converted to true and false.

text

Type: string
Path: settings.[my_val].type = text

Exactly the same as the string type. Use it as an alias if someone doesn't know what to do with string.

stringlist

Type: string
Path: settings.[my_val].type = stringlist

The value must be an array whose array key starts at 0 and increases by 1 per element. This sequence is checked using the internal PHP method array_is_list in order to prevent named array keys from the outset. This also means that comma-separated lists cannot be converted here.

The string type is executed for each array entry.

color

Type: string
Path: settings.[my_val].type = color

Checks whether the specified string can be interpreted as a color code. Entries starting with rgb, rgba and # are permitted here.

For # color codes, for example, the system checks whether they have 3, 6 or 8 digits.

Screenshot demonstration the input fields for different setting types (Part 1)

Screenshot demonstration the input fields for different setting types (Part 2) — A demonstration of the different setting types