[TASK] Revise "Setting user TSconfig" chapter (TYPO3-Documentation#375)

Mainly: - Adjust heading to "Setting user TSconfig" like for "Setting page TSconfig" - Add a TOC - Adjust wording - Add image captions - Add a note about Configuration module with installed lowlevel sysext - Fix error using TCAdefaults in user TSconfig (must be prefix with "page.") Releases: main, 12.4, 11.5
brotkrueml · Oct 7, 2023 · 4053f00 · 4053f00
1 parent b328b87
commit 4053f00
Show file tree

Hide file tree

Showing 2 changed files with 74 additions and 61 deletions.
diff --git a/Documentation/Settings.cfg b/Documentation/Settings.cfg
@@ -54,6 +54,7 @@ ext_core           = https://docs.typo3.org/c/typo3/cms-core/main/en-us/
 # ext_form           = https://docs.typo3.org/c/typo3/cms-form/main/en-us/
 # ext_fsc            = https://docs.typo3.org/c/typo3/cms-fluid-styled-content/main/en-us/
 # ext_indexed_search = https://docs.typo3.org/c/typo3/cms-indexed-search/main/en-us/
+ext_lowlevel       = https://docs.typo3.org/c/typo3/cms-lowlevel/main/en-us/
 # ext_rte_ckeditor   = https://docs.typo3.org/c/typo3/cms-rte-ckeditor/main/en-us/
 # ext_scheduler      = https://docs.typo3.org/c/typo3/cms-scheduler/main/en-us/
 # ext_seo            = https://docs.typo3.org/c/typo3/cms-seo/main/en-us/

diff --git a/Documentation/UsingSetting/UserTSconfig.rst b/Documentation/UsingSetting/UserTSconfig.rst
@@ -1,41 +1,47 @@
 ..  include:: /Includes.rst.txt
-.. index:: User TSconfig
-.. _setting-user-tsconfig:
+..  index:: User TSconfig
+..  _setting-user-tsconfig:
 
-=============
-User TSconfig
-=============
+=====================
+Setting user TSconfig
+=====================
 
-It is recommended to always define custom User TSconfig in a project-specific
-:ref:`sitepackage <t3sitepackage:start>` extension. This way the User TSconfig
+It is recommended to always define custom user TSconfig in a project-specific
+:ref:`sitepackage <t3sitepackage:start>` extension. This way the user TSconfig
 settings can be kept under version control.
 
-.. index:: pair: User TSconfig; Enter data
-.. _userthetsconfigfield:
+.. contents::
+   :local:
 
-Importing the User TSconfig into a backend user or group
+..  index:: pair: User TSconfig; Enter data
+..  _userthetsconfigfield:
+
+Importing the user TSconfig into a backend user or group
 ========================================================
 
-.. rst-class:: bignums
+..  rst-class:: bignums
+
+#.  Open the record of the user or group. Go to
+    :guilabel:`Options > TSconfig`.
 
-#. Open the record of the user or group. Go to
-   :guilabel:`Options > TSconfig`.
+    ..  figure:: /Images/ManualScreenshots/BackendUsers/TSconfigUserInput.png
+        :alt: The TSconfig field in the Options tab of a backend user
+        :class: with-shadow
 
-   .. figure:: /Images/ManualScreenshots/BackendUsers/TSconfigUserInput.png
-      :alt: The TSconfig field in the Options tab of a BE user
+        The :guilabel:`TSconfig` field in the :guilabel:`Options` tab of a backend user
 
-#. Enter the following TSconfig to import a configuration file from your
-   sitepackage:
+#.  Enter the following TSconfig to import a configuration file from your
+    sitepackage:
 
-   .. code-block:: typoscript
-      :caption: TsConfig added in the backend record of a backend user or group
+    ..  code-block:: typoscript
+        :caption: TsConfig added in the backend record of a backend user or group
 
-      @import 'EXT:my_sitepackage/Configuration/TsConfig/User/my_editor.tsconfig'
+        @import 'EXT:my_sitepackage/Configuration/TsConfig/User/my_editor.tsconfig'
 
-This will make all settings from the file available for the user. The file
+This will make all settings in the file available to the user. The file
 itself can be kept under version control together with your sitepackage.
 
-TSconfig defined at user-level overrides TSconfig defined at group-level.
+TSconfig defined at user level overrides TSconfig defined at group level.
 
 If a user is a member of several groups, the TSconfig from each
 group is loaded. The order in which the groups are added to the user in field
@@ -44,17 +50,17 @@ group is loaded. The order in which the groups are added to the user in field
 The TSconfig from latter groups overrides the TSconfig from earlier groups if
 both define the same property.
 
-.. index:: pair: User TSconfig; Default values
-.. _usersettingdefaultusertsconfig:
+..  index:: pair: User TSconfig; Default values
+..  _usersettingdefaultusertsconfig:
 
 Setting default user TSconfig
 =============================
 
 User TSconfig is designed to be individual for users or groups of
-users. However good default values can be defined and overridden by group or
-user specific TSconfig.
+users. However, good defaults can be defined and overridden by group or
+user-specific TSconfig.
 
-In extensions this is easily done by the extension API function,
+In extensions, this is done using the Core API function,
 :php:`\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addUserTSConfig()`.
 In the :file:`ext_localconf.php` file of your extension you can call it
 like this to set a default configuration.
@@ -64,41 +70,46 @@ like this to set a default configuration.
     :caption: EXT:my_sitepackage/ext_localconf.php
 
 There is a global :ref:`TYPO3_CONF_VARS <t3coreapi:typo3ConfVars>` value called
-:php:`$GLOBALS['TYPO3_CONF_VARS']['BE']['defaultUserTSconfig'] <t3coreapi:typo3ConfVars_be_defaultUserTSconfig>`.
-The API function above adds content to that array. The array value itself
-however should **not** be changed or set directly without using the API.
+:ref:`$GLOBALS['TYPO3_CONF_VARS']['BE']['defaultUserTSconfig'] <t3coreapi:typo3ConfVars_be_defaultUserTSconfig>`.
+The API function above adds content to that array. However, the array value
+itself should **not** be changed or set directly without using the API.
 
 
-.. index:: pair: User TSconfig; Verify configuration
-.. _userverifyingthefinalconfiguration:
+..  index:: pair: User TSconfig; Verify configuration
+..  _userverifyingthefinalconfiguration:
 
 Verify the final configuration
 ==============================
 
-The full User TSconfig of the currently logged-in backend user can be viewed
-using the :guilabel:`System > Configuration` module and choosing the
+The full user TSconfig of the currently logged-in backend user can be viewed
+using the :guilabel:`System > Configuration` backend module and choosing the
 action :guilabel:`$GLOBALS['BE_USER']->getTSConfig() (User TSconfig)`. However
 this module can only be accessed by admins.
 
-.. figure:: /Images/ManualScreenshots/Configuration/UserTSconfigOverview.png
-    :alt: Viewing User TSconfig using the Configuration module
+..  figure:: /Images/ManualScreenshots/Configuration/UserTSconfigOverview.png
+    :alt: Viewing user TSconfig using the Configuration module
+    :class: with-shadow
+
+    Viewing user TSconfig using the :guilabel:`Configuration` module
 
+The :guilabel:`Configuration` module is available with installed
+:doc:`lowlevel <ext_lowlevel:Index>` system extension.
 
-.. index:: pair: User TSconfig; Override values
-.. _user-override-modify-values:
+..  index:: pair: User TSconfig; Override values
+..  _user-override-modify-values:
 
 Override and modify values
 ===========================
 
 Properties, which are set in the TSconfig field of a group, are valid
 for all users of that group.
 
-Values which are set in one group can be overridden and
-:ref:`modified <t3coreapi:typoscript-syntax-syntax-value-modification>` in the same or
-another group. If a user is a member of multiple groups, the TSconfig
-settings are evaluated in *the* order, in which the groups are included
-in the user account: When you are editing the backend user, the
-selected groups are evaluated from top to bottom.
+Values set in one group can be overridden and
+:ref:`modified <t3coreapi:typoscript-syntax-syntax-value-modification>` in the
+same or another group. If a user is a member of multiple groups, the TSconfig
+settings are evaluated in the order in which the groups are included in the
+user account: When editing the backend user, the selected groups are evaluated
+from top to bottom.
 
 **Example:**
 
@@ -120,15 +131,15 @@ selected groups are evaluated from top to bottom.
 
 *   You get the value "bold,italic".
 
-Finally you can override or
-:ref:`modify <t3coreapi:typoscript-syntax-syntax-value-modification>`
-settings from groups, of which your user is a member, in the User TSconfig
+Finally, you can override or
+:ref:`modify <t3coreapi:typoscript-syntax-syntax-value-modification>` the
+settings from groups that your user is a member of in the user TSconfig
 field of that specific user.
 
 **Example:**
 
 Let's say the user is a member of a *usergroup* with this
-configuration
+configuration:
 
 ..  code-block:: typoscript
     :caption: EXT:site_package/Configuration/page.tsconfig
@@ -143,27 +154,27 @@ Then we set the following values in the TSconfig field of the specific *user*.
 ..  code-block:: typoscript
     :caption: EXT:site_package/Configuration/user.tsconfig
 
-    TCAdefaults.tt_content.header = 234
+    page.TCAdefaults.tt_content.header = 234
     options.clearCache.all = 1
 
 This would override the default value of the header ("234") and add the
 clear cache option. The default value of the hidden field is not
 changed and simply inherited directly from the group.
 
 
-.. index:: User TSconfig; Override page TSconfig
-.. _userrelationshiptovaluessetinpagetsconfig:
-.. _pageoverridingpagetsconfigwithusertsconfig:
+..  index:: User TSconfig; Override page TSconfig
+..  _userrelationshiptovaluessetinpagetsconfig:
+..  _pageoverridingpagetsconfigwithusertsconfig:
 
-Overriding Page TSconfig in User TSconfig
+Overriding page TSconfig in user TSconfig
 =========================================
 
-All properties from Page TSconfig can be **overridden** in User TSconfig by
-prepending the property name with `page.`.
+All properties from page TSconfig can be **overridden** in user TSconfig by
+prepending the property name with :typoscript:`page.`.
 
-When a Page TSconfig property is set in **User** TSconfig that way, regardless
+When a page TSconfig property is set in **user** TSconfig that way, regardless
 of whether it is in the TSconfig field of a
-group or a user, it **overrides** the value of the according **Page** TSconfig property.
+group or a user, it **overrides** the value of the according **page** TSconfig property.
 
 To illustrate this feature let's say the action
 :guilabel:`Web > Info > Localization Overview` has been disabled via Page
@@ -177,8 +188,9 @@ TSconfig:
     }
 
 If we activate this configuration in the TSconfig of a certain backend user, that
-user would still be able to select this menu item because the value of his User TSconfig
-overrides the same value set in the Page TSconfig, just prefixed with `page.`:
+user would still be able to select this menu item because the value of his user TSconfig
+overrides the same value set in the page TSconfig, just prefixed with
+:typoscript:`page.`:
 
 ..  code-block:: typoscript
     :caption: EXT:site_package/Configuration/user.tsconfig
@@ -187,11 +199,11 @@ overrides the same value set in the Page TSconfig, just prefixed with `page.`:
         TYPO3\CMS\Info\Controller\TranslationStatusController = 1
     }
 
-.. attention::
+..  attention::
 
     It is **not** possible to *reference* the value of a property from page
     TSconfig and to *modify* this value in user TSconfig! If you set a property
-    in user TSconfig, which already had been set in *Page* TSconfig, then the
+    in user TSconfig, which already had been set in *page* TSconfig, then the
     value from page TSconfig will be overridden.
 
     The result of the example below is *not* the value "bold,italic",