TypoScript configuration

TYPO3 uses TypoScript as a specific language to configure a website. TypoScript is a very powerful tool in the TYPO3 universe, because it allows integrators to configure and manipulate almost every aspect of the system and customize a TYPO3 instance to very specific needs of their customers. It is important to highlight, that TypoScript is not a programming language, so you do not need to be a software developer to fine tune TYPO3. However, due to the complexity of TYPO3 and its configuration options, quite comprehensive documentation about TypoScript exists, which can be overwhelming sometimes.

As part of this tutorial, we focus on the basics only and how to apply them. A documentation about TypoScript and all its objects, properties and functions can be found in the TypoScript Reference.

Files and directories

First of all, we create two new files in the site package directory structure, which will contain all TypoScript configurations. By following the official conventions of their file and directory naming, TYPO3 knows how to include them automatically.


As shown above, these two files are constants.typoscript and setup.typoscript inside the Configuration/TypoScript/ folder. The Fluid template files we have created in the previous step are located in the Resources/ directory, but not listed above for clarity reasons.

TypoScript constants

TypoScript constants are used to set values that can be used in the TypoScript setup through out the project.

It is best practise to use them for values that might want to be changed later on like paths, ids of important pages (contact, imprint, a system folder that contains certain records, ...).

You could for example define the title of your page in a TypoScript constant:

mysitepackage.page.title = My cool project

And later on use it somewhere in your TypoScript setup to output it on your page:

lib.footer = TEXT
lib.footer.value = {$mysitepackage.page.title}
lib.footer.wrap = <footer> &copy | </footer>

Add the following lines to file constants.typoscript:

@import 'EXT:fluid_styled_content/Configuration/TypoScript/constants.typoscript'

page {
  fluidtemplate {
    layoutRootPath = EXT:site_package/Resources/Private/Layouts/Page/
    partialRootPath = EXT:site_package/Resources/Private/Partials/Page/
    templateRootPath = EXT:site_package/Resources/Private/Templates/Page/

Line 1 includes the default constants from the system extension fluid_styled_content (which is part of the TYPO3 Core).

The following lines define some constants with paths to the template directories that we defined in the previous chapter.

The part EXT: of the paths will be automatically replaced by the path to your extensions location, usually something like /typo3conf/ext/.

You can read more about TypoScript constants in the TypoScript reference.

TypoScript setup

The setup.typoscript will only contain imports in our example. It is considered best practice to split up large TypoScript files into logical parts. This improves maintainability and collaboration. In the example below we split up the TypoScript setup file into sections by didactic reasons.

@import 'EXT:fluid_styled_content/Configuration/TypoScript/setup.typoscript'
@import 'EXT:site_package/Configuration/TypoScript/Setup/*.typoscript'

Line 1 imports the default setup from the system extension fluid_styled_content (which is part of the TYPO3 Core).

Line 2 imports all files ending on .typoscript from the specified folder. It does however not import files from sub folders. Those would have to be imported separately.

Hello World: The PAGE object

In order to create any output at all we first need to define a PAGE. The example below would output an empty page:

page = PAGE
page {
  typeNum = 0
  // 10 = TEXT
  //10.value = Hello World!

If you remove the comments // before line 4 and 5 there would be an output of "Hello World!".

You can read more about the top-level PAGE object in the TypoScript reference.

The parameter typeNum is mandatory. Setting it to 0 enables the page to be called. If you would set it to any value above there the page would need to be called with an additional parameter like &type=12345 to the url.

Part 1: Fluid template section

First, create a file called Part1FluidTemplateSection.typoscript in the folder Configuration/TypoScript/Setup/ with the following content:

// Part 1: Fluid template section
page.10 {
  templateName = TEXT
  templateName {
    cObject = TEXT
    cObject {
      data = pagelayout
      required = 1
      case = ucfirst
      split {
        token = pagets__
        cObjNum = 1
        1.current = 1

    ifEmpty = Default

  templateRootPaths {
    0 = EXT:site_package/Resources/Private/Templates/Page/
    1 = {$page.fluidtemplate.templateRootPath}

  partialRootPaths {
    0 = EXT:site_package/Resources/Private/Partials/Page/
    1 = {$page.fluidtemplate.partialRootPath}

  layoutRootPaths {
    0 = EXT:site_package/Resources/Private/Layouts/Page/
    1 = {$page.fluidtemplate.layoutRootPath}

Line 1 is a comment. All lines starting with // or # will be ignored by the parser. In TypoScript it is however not possible to have a comment after code in a line as you might be used from PHP of Java.

Line 2 configures that the template rendering engine Fluid should be used to generate the page output.

The name of the template to be used is determined in line 4 ff. The current backend layout is stored in the gettext function pagelayout. By default these start with pagets__ followed by a lowercase keyword. By stdwrap we replace the first part and change the case such that the backend type pagets__twoColumns will call the template of name TwoColumns.

Line 21 ff define the storage paths for the templates. Template files are stored here in the aforementioned folders Templates/Page/, Partials/Page/ and Layouts/Page/.

Part 2 and 3: CSS and JavaScript file inclusion

We have combined part 2 and 3, because the inclusion of CSS and JavaScript files in TypoScript is pretty straight forward. Create a file called Part2CssFileInclusion.typoscript in the folder Configuration/TypoScript/Setup/ with the following content:

page {
  // Part 2: CSS file inclusion
  includeCSS {
    bootstrap = https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css
    bootstrap.external = 1
    website = EXT:site_package/Resources/Public/Css/website.css

  // Part 3: JavaScript file inclusion
  includeJSFooter {
    jquery = https://code.jquery.com/jquery-3.2.1.slim.min.js
    jquery.external = 1
    popper = https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.3/umd/popper.min.js
    popper.external = 1
    bootstrap = https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js
    bootstrap.external = 1
    website = EXT:site_package/Resources/Public/JavaScript/website.js

Section includeCSS { ... } instructs TYPO3 to include the CSS from the Bootstrap library from an external source. It also includes file website.css from the site package extension. We have copied this file into the appropriate folder before.

Section includeJSFooter { ... } includes four JavaScript files in total. The first three are externally hosted files (jQuery, Popper and Bootstrap). Therefore, .external = 1 forces TYPO3, not to check for their local existence. The fourth JavaScript file is the file we added before to the site package extension itself.

You can also include CSS or JavaScript per-component in your Fluid template or by PHP. See Assets (CSS, JavaScript, Media).

Part 4: Global site configuration

It is possible to configure multiple options globally in the section Typoscript object config. None of them is necessary to make the example here run. So we just included two configuration values as an example. Read more about them here: TypoScript Reference.

// Part 4: global site configuration
config {
  # Adjust the title tag to be displayed as “website - page title”
  pageTitleSeparator = -
  pageTitleSeparator.noTrimWrap = | | |

  # Display the Admin Panel at the bottom of pages to logged in backend users
  admPanel = 1

This is all required for the "TypoScript Configuration" part at this point. The next step deals with the extension configuration and adds a couple of PHP files, so let's move on.