File imports
Changed in version 14.0
The old school <INCLUDE_
syntax has been deprecated
with version 13.4 and was removed with TYPO3 v14.0.
See Migration from <INCLUDE_TYPOSCRIPT: to @import.
To structure and reuse single TypoScript snippets and not stuffing everything into one file or record, the syntax allows loading TypoScript content from sub files.
The keyword @import
is a syntax construct and
thus available in both frontend TypoScript and backend TSconfig.
@import
allows including additional files using wildcards on the file
level. Wildcards in paths are not allowed.
The TypoScript parser allows to place @import
within condition
bodies, which allows conditional imports with @import
.
@import
is not allowed to be placed within code blocks
and breaks any curly braces level, resetting current scope
to top level.
@import
This keyword allows including files inspired by a syntax similar to SASS
.
It is restricted, but still allows wildcards on file level. Single files must end
with .typoscript
if included in frontend Typoscript. In backend TSconfig,
single files should end with .tsconfig
, but may end with
.typoscript
as well (for now).
The include logic is a bit more restrictive with TYPO3 v12, previous versions have been slightly more relaxed in this regard. See this changelog for more details.
The following rules apply:
- Multiple files are imported in alphabetical order. If a special loading order is desired it is common to prefix the filenames with numbers that increase for files that shall be loaded later.
- Recursion is allowed: Imported files can have
@import
statements. Changed in version 12.0
It is allowed to put
@import
within a condition. This example imports the additional file only if a frontend user is logged in:[frontend.user.isLoggedIn] @import './userIsLoggedIn.typoscript' [END]
Copied!- Directory imports are not recursive, meaning that a directory import does not automatically travel down its subdirectories.
- Quoting the filename is necessary with the new syntax. Either double quotes (") or single quotes (') can be used.
- Wildcards
*
are only allowed on file level, not on directory level. Only a single wildcard character is allowed. - Includes relative to the current file location are allowed using
./
as prefix. - Includes must start with
EXT:
if not relative. Loading files outside of extensions is not possible. - Directory traversal using
../
is not allowed.
Some examples:
# Import a single file
@import 'EXT:my_extension/Configuration/TypoScript/randomfile.typoscript'
# Import multiple files in a single directory, sorted by file name
@import 'EXT:my_extension/Configuration/TypoScript/*.typoscript'
# It's possible to omit the file ending. For frontend TypoScript, ".typoscript" is
# appended automatically, backend TSconfig allows both ".typoscript" and ".tsconfig"
@import 'EXT:my_extension/Configuration/TypoScript/'
# Import files starting with "foo", ending with ".typoscript" (frontend)
@import 'EXT:my_extension/Configuration/TypoScript/foo*'
# Import files ending with ".setup.typoscript"
@import 'EXT:my_extension/Configuration/TypoScript/*.setup.typoscript'
# Import "bar.typoscript" relative to current file
@import './bar.typoscript'
# Import all ".setup.typoscript" files in sub directory relative to current file
@import './subDirectory/*.setup.typoscript'
Alternatives to using file imports
The following features can make file inclusion unnecessary:
- Automatic global inclusion of user TSconfig of extensions
- Automatic global inclusion of page TSconfig of extensions
- Automatic page TSconfig on site level
- TypoScript provider for sites and sets automatically loads TypoScript per site when the site set is included in the site configuration.