[TASK] fix list formatting
[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/Configuration/TypoScript/randomfile.typoscript'
23
24 # Import multiple files in a single directory, sorted by file name
25 @import 'EXT:myproject/Configuration/TypoScript/*.typoscript'
26
27 # Import all files in a directory
28 @import 'EXT:myproject/Configuration/TypoScript/'
29
30 # It's possible to omit the file ending, then "typoscript" is automatically added
31 @import 'EXT:myproject/Configuration/TypoScript/'
32
33 The main benefits of `@import` over using `<INCLUDE_TYPOSCRIPT>` are:
34
35 - Less error-prone when adding statements to TypoScript
36
37 - Easier to read what should be included (files, folders - instead of `FILE:` and `DIR:` syntax)
38
39 - @import is more speaking than a pseudo-XML syntax
40
41 The following rules apply:
42
43 - If multiple files are found, the file name is important in which order the files (sorted
44 alphabetically by filename)
45
46 - Recursive inclusion of files (@import within @import is possible)
47
48 - It is not possible to use a condition as possible with <INCLUDE_TYPOSCRIPT condition=""> as its
49 sole purpose is to include files, which happens before the actual real condition matching happens,
50 and the INCLUDE_TYPOSCRIPT condition syntax is a conceptual mistake, and should be avoided.
51
52 - Both `<INCLUDE_TYPOSCRIPT>` and `@import` can work side-by-side in the same project
53
54 - If a directory is included, it will not include files recursively
55
56 - Quoting of the filename is necessary, both double quotes (") and single tickst (') can be used
57
58 The syntax is designed to stay, and @import is not intended to be extended with more logic in the
59 future. However, it may be possible that TypoScript will get more preparsing logic via the @ annotation.
60
61 Under the hood, Symfony Finder is used to detect files. This makes globbing (* syntax) possible.
62
63 .. index:: TypoScript, Frontend