aabdba240cb185529e34fc513dc2aa679c8d04cd
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / 9.0 / Feature-82812-NewSyntaxForImportingTypoScriptFiles.rst
1 .. include:: ../../Includes.txt
2
3 ===========================================================
4 Feature: #82812 - New syntax for importing TypoScript files
5 ===========================================================
6
7 See :issue:`82812`
8
9 Description
10 ===========
11
12 A new syntax for importing external TypoScript files has been introduced, which acts as a preprocessor
13 before the actual parsing (Condition evaluation) is made.
14
15 It's main purpose is ease the use of TypoScript includes and make it easier for integrators and
16 frontend developers to work with distributed TypoScript files. The syntax is inspired by SASS
17 imports and works as follows:
18
19 .. code-block:: typoscript
20
21 # Import a single file
22 @import 'EXT:myproject/TypoScript/Configuration/randomfile.typoscript'
23
24 # Import multiple files in a single directory, sorted by file name
25 @import 'EXT:myproject/TypoScript/Configuration/*.typoscript'
26
27 # Import all files in a directory
28 @import 'EXT:myproject/TypoScript/Configuration/'
29
30 # It's possible to omit the file ending, then "typoscript" is automatically added
31 @import 'EXT:myproject/TypoScript/Configuration/'
32
33 The main benefits of `@import` over using `<INCLUDE_TYPOSCRIPT>` are:
34 - Less error-prone when adding statements to TypoScript
35 - Easier to read what should be included (files, folders - instead of `FILE:` and `DIR:` syntax)
36 - @import is more speaking than a pseudo-XML syntax
37
38 The following rules apply:
39 - If multiple files are found, the file name is important in which order the files (sorted
40 alphabetically by filename)
41 - Recursive inclusion of files (@import within @import is possible)
42 - It is not possible to use a condition as possible with <INCLUDE_TYPOSCRIPT condition=""> as its
43 sole purpose is to include files, which happens before the actual real condition matching happens,
44 and the INCLUDE_TYPOSCRIPT condition syntax is a conceptual mistake, and should be avoided.
45 - Both `<INCLUDE_TYPOSCRIPT>` and `@import` can work side-by-side in the same project
46 - If a directory is included, it will not include files recursively
47 - Quoting of the filename is necessary, both double quotes (") and single tickst (') can be used
48
49 The syntax is designed to stay, and @import is not intended to be extended with more logic in the
50 future. However, it may be possible that TypoScript will get more preparsing logic via the @ annotation.
51
52 Under the hood, Symfony Finder is used to detect files. This makes globbing (* syntax) possible.
53
54 .. index:: TypoScript, Frontend