[BUGFIX] Fix site handling documentation
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / 9.2 / Feature-84581-SiteHandling.rst
1 .. include:: ../../Includes.txt
2
3 =========================================
4 Feature: #84581 - Introduce Site Handling
5 =========================================
6
7 See :issue:`84581`
8
9 Description
10 ===========
11
12 Site Handling has been added to TYPO3.
13
14 Its goal is to make managing multiple sites easier to understand and faster to do. Sites bring a variety of new
15 concepts to TYPO3 which we will explain below.
16
17 Take your time and read through the entire document since some concepts rely on each other.
18
19
20 typo3conf/sites folder
21 ----------------------
22
23 New sites will live in the folder `typo3conf/sites/`. In the first iteration this folder will contain a file called
24 `config.yaml` which holds all configuration for a given site.
25
26 Note that if you are using a composer based installation, then the file location is `<project-root>/config/sites/<identifier>/config.yaml`
27
28 In the future this folder can (and should) be used for more files like Fluid templates, and Backend layouts.
29
30
31 config.yaml
32 -----------
33
34 .. code::
35
36 # the rootPage Id (see below)
37 rootPageId: 12
38 # my base domain to run this site on. It either accepts a fully qualified URL or "/" to react to any domain name
39 base: 'https://www.example.com/'
40 # The language array
41 languages:
42 -
43 # the TYPO3 sys_language_uid as you know it since... ever
44 languageId: '0'
45 # The internal name for this language. Unused for now, but in the future this will affect display in the backend
46 title: English
47 # optional navigation title which is used in HMENU.special = language
48 navigationTitle: ''
49 # Language base. Accepts either a fully qualified URL or a path segment like "/en/".
50 base: /
51 # sets the locale during frontend rendering
52 locale: en_US.UTF-8
53 # two-letter code for the language according to ISO-639 nomenclature (see https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)
54 iso-639-1: en
55 # FE href language
56 hreflang: en-US
57 # FE text direction
58 direction: ltr
59 # Language Identifier to use in localLang XLIFF files
60 typo3Language: default
61 # Flag Identifier
62 flag: gb
63 -
64 languageId: '1'
65 title: 'danish'
66 navigationTitle: Dansk
67 base: /da/
68 locale: dk_DK.UTF-8
69 iso-639-1: da
70 hreflang: dk-DK
71 direction: ltr
72 typo3Language: default
73 flag: dk
74 fallbackType: strict
75 -
76 languageId: '2'
77 title: Deutsch
78 navigationTitle: ''
79 base: 'https://www.beispiel.de'
80 locale: de_DE.UTF-8
81 iso-639-1: de
82 hreflang: de-DE
83 direction: ltr
84 typo3Language: de
85 flag: de
86 # Enable content fallback
87 fallbackType: fallback
88 # Content fallback mode (order is important)
89 fallbacks: '2,1,0'
90 # Error Handling Array (order is important here)
91 # Error Handlers will check the given status code, but the special value "0" will react to any error not configured
92 # elsewhere in this configuration.
93 errorHandling:
94 -
95 # HTTP Status Code to react to
96 errorCode: '404'
97 # The used ErrorHandler. In this case, it's "Display content from Page". See examples below for available options.
98 errorHandler: Page
99 # href to the content source to display (accepts both fully qualified URLs as well as TYPO3 internal link syntax
100 errorContentSource: 't3://page?uid=8'
101 -
102 errorCode: '403'
103 errorHandler: Fluid
104 # Path to the Template File to show
105 errorFluidTemplate: 'EXT:my_extension/Resources/Private/Templates/ErrorPages/403.html'
106 # Optional Templates root path
107 errorFluidTemplatesRootPath: 'EXT:my_extension/Resources/Private/Templates/ErrorPages'
108 # Optional Layouts root path
109 errorFluidLayoutsRootPath: 'EXT:my_extension/Resources/Private/Layouts/ErrorPages'
110 # Optional Partials root path
111 errorFluidPartialsRootPath: 'EXT:my_extension/Resources/Private/Partials/ErrorPages'
112 -
113 errorCode: '0'
114 errorHandler: PHP
115 # Fully qualified class name to a class that implements PageErrorHandlerInterface
116 errorPhpClassFQCN: Vendor\ExtensionName\ErrorHandlers\GenericErrorhandler
117
118
119 All settings can also be edited via the backend module `Site Management > Configuration`.
120
121 Keep in mind that due to the nature of the module, comments or additional values in your :file:`config.yaml` file
122 **will** get deleted on saving.
123
124
125 site identifier
126 ---------------
127
128 The site identifier is the name of the folder within `typo3conf/sites/` that will hold your configuration file(s). When
129 choosing an identifier make sure to stick to ASCII but you may also use `-`, `_` and `.` for convenience.
130
131
132 rootPageId
133 ----------
134
135 Root pages are identified by one of these two properties:
136
137 * they are direct descendants of PID 0 (the root root page of TYPO3)
138 * they have the "Use as Root Page" property in `pages` set to true.
139
140
141 Configuration
142 =============
143
144 The new backend module relies on FormEngine to render the edit interface. Since the form data is not stored in
145 database records but in :file:`.yml` files, a couple of details have been extended of the default FormEngine code.
146
147 The render configuration is stored in :file:`typo3/sysext/backend/Configuration/SiteConfiguration/` in a format
148 syntactically identical to TCA. However, this is **not** loaded into :php:`$GLOBALS['TCA']` scope, and only a small
149 subset of TCA features is supported.
150
151 **Extending site configuration is experimental** and may change any time.
152
153 In practice the configuration can be extended, but only with very simple fields like the basic config type :php:`input`,
154 and even for this one not all features are possible, for example the :php:`eval` options are limited. The code throws
155 exceptions or just ignores settings it does not support. While some of the limits may be relaxed a bit over time, many
156 will be kept. The goal is to allow developers to extend the site configuration with a couple of simple things like
157 an input field for a Google API key. However it is **not possible to extend with complex TCA** like inline relations,
158 database driven select fields, Flex Form handling and similar.
159
160 The example below shows the experimental feature adding a field to site in an extensions file
161 :file:`Configuration/SiteConfiguration/Overrides/sites.php`. Note the helper methods of class
162 :php:`TYPO3\CMS\core\Utility\ExtensionManagementUtility` can not be used.
163
164 .. code-block:: php
165
166 <?php
167 // Experimental example to add a new field to the site configuration
168
169 // Configure a new simple required input field to site
170 $GLOBALS['SiteConfiguration']['site']['columns']['myNewField'] = [
171 'label' => 'A new custom field',
172 'config' => [
173 'type' => 'input',
174 'eval' => 'required',
175 ],
176 ];
177 // And add it to showitem
178 $GLOBALS['SiteConfiguration']['site']['types']['0']['showitem'] = str_replace(
179 'base,',
180 'base, myNewField, ',
181 $GLOBALS['SiteConfiguration']['site']['types']['0']['showitem']
182 );
183
184 The field will be shown in the edit form of the configuration module and it's value stored in the .yml
185 file. Using the site object :php:`TYPO3\CMS\core\Site\Entity\Site`, the value can be fetched using
186 :php:`->getConfiguration()['myNewField']`.
187
188
189 Impact
190 ======
191
192 The following TypoScript settings will be set based on `config.yaml` rather than needing to have them in your TypoScript
193 template:
194
195 * config.language
196 * config.htmlTag_dir
197 * config.htmlTag_langKey
198 * config.sys_language_uid
199 * config.sys_language_mode
200 * config.sys_language_isocode
201 * config.sys_language_isocode_default
202
203
204 Links to pages within a site can now be generated via **any** access of TYPO3, so in both BE and FE as well as CLI mode.
205
206 .. index:: Backend, Frontend, TypoScript