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

site_package/
site_package/Configuration/
site_package/Configuration/TypoScript/
site_package/Configuration/TypoScript/Setup/
site_package/Configuration/TypoScript/constants.typoscript
site_package/Configuration/TypoScript/setup.typoscript
site_package/Resources/
site_package/Resources/...

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

Add the following lines to file constants.typoscript:

EXT:site_package/Configuration/TypoScript/constants.typoscript
1
2
3
4
5
6
7
8
9
@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 “Fluid Styled Content” extension (which is part of the TYPO3 Core).

TypoScript constants are used to set values that can be used in TypoScript 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 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.

EXT:site_package/Configuration/TypoScript/setup.typoscript
1
2
@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 “Fluid Styled Content” extension (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:

EXT:site_package/Configuration/TypoScript/Setup/Page.typoscript
1
2
3
4
5
6
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!”. But of course we want to output our Fluid template.

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

The parameter typeNum is mandatory. Setting it to null enables the page to be called without adding an additional parameter &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:

EXT:site_package/Configuration/TypoScript/Setup/Part6ProcessedContent
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
page {
  10 {
    dataProcessing {
      //10 = TYPO3\CMS\Frontend\DataProcessing\MenuProcessor
      20 = TYPO3\CMS\Frontend\DataProcessing\DatabaseQueryProcessor
      20 {
        table = tt_content
        orderBy = sorting
        where = colPos = 0
        as = mainContent
      }
      30 = TYPO3\CMS\Frontend\DataProcessing\DatabaseQueryProcessor
      30 {
        table = tt_content
        orderBy = sorting
        where = colPos = 1
        as = jumbotronContent
      }
      40 = TYPO3\CMS\Frontend\DataProcessing\DatabaseQueryProcessor
      40 {
        table = tt_content
        orderBy = sorting
        where = colPos = 2
        as = sidebarContent
      }
    }
  }
}

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:

EXT:site_package/Configuration/TypoScript/Setup/Part2CssFileInclusion.typoscript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
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.

EXT:site_package/Configuration/TypoScript/Setup/Part4GlobalConfiguration.typoscript
1
2
3
4
5
6
7
8
9
// 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.