[Backport 12.4] [TASK] styleguide: Improve user TSconfig setup (#495)

* [TASK] styleguide: Improve user TSconfig options **No text changes made** - correct indentation - introduce confvals - move large codesnippet to file releases: main, 12.4, 11.5 * Apply suggestions from code review Co-authored-by: Chris Müller <[email protected]> --------- Co-authored-by: lina.wolf <[email protected]> Co-authored-by: Lina Wolf <[email protected]> Co-authored-by: Chris Müller <[email protected]>
TYPO3-Documentation · Apr 20, 2024 · 4a47430 · 4a47430
1 parent 1cc2ee9
commit 4a47430
Show file tree

Hide file tree

Showing 2 changed files with 140 additions and 90 deletions.
diff --git a/Documentation/TSconfig/Documentation/UserTsconfig/Setup.rst b/Documentation/TSconfig/Documentation/UserTsconfig/Setup.rst
@@ -1,8 +1,9 @@
-.. include:: /Includes.rst.txt
-.. index::
-   User settings; override
-   User settings; default
-.. _usersetup:
+..  include:: /Includes.rst.txt
+..  index::
+    User settings; override
+    User settings; default
+..  _usersetup:
+..  _user-setup:
 
 =====
 setup
@@ -12,195 +13,224 @@ Default values and override values for the :guilabel:`User Settings` module.
 
 The :guilabel:`User > User settings` module may only represent a subset of the options from the table below.
 
-.. figure:: /Images/ManualScreenshots/UserSettings/UserSettings.png
+..  figure:: /Images/ManualScreenshots/UserSettings/UserSettings.png
     :alt: Default values and overriding values in the "User > User settings" module
 
     Default values and overriding values in the :guilabel:`User > User settings` module
 
 Properties from the list below are available the different prefixes `setup.default` and `setup.override`,
 and there is another prefix to hide single fields:
 
+..  _user-setup-properties:
+
+Properties
+==========
+
+..  contents::
+    :depth: 2
+    :local:
+
+..  _user-setup-default:
+
 setup.default.[someProperty]
+----------------------------
+
+..  confval:: setup.default.[someProperty]
+    :name: user-setup-default
+    :type: any
+
     This sets *default* values of the property. A user may override these
     using its :guilabel:`User Settings` module. This affects only *new* users who did
     not login yet. It is not usually not possible to set new defaults for users
     who already logged in at least once. The only way to apply new defaults to
     existing users is by :guilabel:`Reset Backend User Preferences` in the
     :guilabel:`Admin tools > Maintenance` section of the install tool.
 
-    .. code-block:: typoscript
-       :caption: EXT:site_package/Configuration/user.tsconfig
-
-       [backend.user.isAdmin]
-          # Some settings an administrator might find helpful
-          setup.default {
-             recursiveDelete = 1
-             copyLevels = 99
-             moduleData {
-                # Defaulting some options of the Template/TypoScript backend module
-                web_ts {
-                   # Pre-select 'Object browser' instead of 'Constant editor'
-                   function = TYPO3\CMS\Tstemplate\Controller\TypoScriptTemplateObjectBrowserModuleFunctionController
-                   # Pre-select 'Setup' instead of 'Constants'
-                   ts_browser_type = setup
-                   # The other settings
-                   ts_browser_const = subst
-                   ts_browser_fixedLgd = 0
-                   ts_browser_showComments = 1
-                }
-             }
-          }
-       [END]
+    ..  literalinclude:: _Setup/_user-setup-default.tsconfig
+        :language: typoscript
+        :caption: EXT:site_package/Configuration/user.tsconfig
+
+
+..  _user-setup-override:
 
 setup.override.[someProperty]
+-----------------------------
+
+..  confval:: setup.override.[someProperty]
+    :name: user-setup-override
+    :type: mixed
+
     This forces values for the properties of the list below, a user can not override these
     setting in its :guilabel:`User settings` module. So, overriding values will be impossible for the
     user to change himself and no matter what the current value is, the overriding
     value will overrule it.
 
-    .. attention::
+    ..  attention::
         There is a tricky aspect to these `setup.override`: If first you have set a
         value by `setup.override` and then remove it again, you will experience
         that the value persists to exist. This is because it is saved in the
         backend user's profile. Therefore, if you have once set a value, do
         *not* remove it again but rather set it blank if you want to disable
         the effect again!
 
+..  _user-setup-fields-fieldName-disabled:
+
 setup.fields.[fieldName].disabled
+---------------------------------
+
+..  confval:: setup.fields.[fieldName].disabled
+    :name: user-setup-fields-fieldName-disabled
+    :type: boolean
+
     On top of being able to set default values or override them, it is also possible to
     hide fields in the :guilabel:`User Settings` module, using `setup.fields.[fieldName].disabled = 1`.
     You can find the names of the fields in the :guilabel:`Configuration` module by browsing the "User Settings" array, example:
 
-    .. code-block:: typoscript
-       :caption: EXT:site_package/Configuration/user.tsconfig
+    ..  code-block:: typoscript
+        :caption: EXT:site_package/Configuration/user.tsconfig
 
-       # Do not show the 'emailMeAtLogin' field to the user in "User Settings" module
-       setup.fields.emailMeAtLogin.disabled = 1
+        # Do not show the 'emailMeAtLogin' field to the user in "User Settings" module
+        setup.fields.emailMeAtLogin.disabled = 1
 
-       # And force the value of this field to be set to 1
-       setup.override.emailMeAtLogin = 1
+        # And force the value of this field to be set to 1
+        setup.override.emailMeAtLogin = 1
 
+..  index::  User settings; Format of window title in backend
 
-.. index::
-   User settings; Format of window title in backend
+..  _user-setup-backendTitleFormat:
 
 backendTitleFormat
-==================
+------------------
+
+..  confval:: backendTitleFormat
+    :name: user-setup-backendTitleFormat
+    :type: string
 
-:aspect:`Datatype`
-   string
+    Format of window title in backend. Possible values:
 
-:aspect:`Description`
-   Format of window title in backend. Possible values:
+    `titleFirst`
+        [title] · [sitename]
+    `sitenameFirst`
+        [sitename] · [title]
 
-   `titleFirst`
-      [title] · [sitename]
-   `sitenameFirst`
-      [sitename] · [title]
 
+..  index:: User settings; Copy levels
 
-.. index::
-   User settings; Copy levels
+..  _user-setup-copyLevels:
 
 copyLevels
-==========
+----------
 
-:aspect:`Datatype`
-    positive integer
+..  confval:: copyLevels
+    :name: user-setup-copyLevels
+    :type: positive integer
 
-:aspect:`Description`
     Recursive Copy: Enter the number of page sub-levels to include, when a page is copied
 
 
-.. index:: File upload; In doc module
+..  index:: File upload; In doc module
+
+..  _user-setup-edit-docModuleUpload:
 
 edit_docModuleUpload
-====================
+--------------------
 
-:aspect:`Datatype`
-    boolean
+..  confval:: edit_docModuleUpload
+    :name: user-setup-edit-docModuleUpload
+    :type: boolean
 
-:aspect:`Description`
     Allow file upload directly from file reference fields within backend forms.
 
-    .. note::
+    ..  note::
         The uploaded file will be stored in the default upload folder,
         see :ref:`user TSconfig <useroptions-defaultUploadFolder>` and :ref:`page TSconfig <pagedefaultuploadfolder>`
 
 
-.. index:: Email me at login
+..  index:: Email me at login
+
+..  _user-setup-emailMeAtLogin:
 
 emailMeAtLogin
-==============
+--------------
 
-:aspect:`Datatype`
-    boolean
+..  confval:: emailMeAtLogin
+    :name: user-setup-emailMeAtLogin
+    :type:  boolean
 
-:aspect:`Description`
     Notify me by email, when somebody logs into my account
 
 
-.. index:: Backend; Language
+..  index:: Backend; Language
+
+..  _user-setup-lang:
 
 lang
-====
+----
 
-:aspect:`Datatype`
-    language-key
+..  confval:: lang
+    :name: user-setup-lang
+    :type: language-key
 
-:aspect:`Description`
     One of the language keys. For current options see
     :ref:`t3coreapi:i18n_languages`, for example `dk`, `de`, `es` etc.
 
 
-.. index:: Records; Hide at copy
+..  index:: Records; Hide at copy
+
+..  _user-setup-neverHideAtCopy:
 
 neverHideAtCopy
-===============
+---------------
 
-:aspect:`Datatype`
-    boolean
+..  confval:: neverHideAtCopy
+    :name: user-setup-neverHideAtCopy
+    :type: boolean
 
-:aspect:`Description`
     If set, then the hideAtCopy feature for records in TCE will not be used.
 
 
-.. index:: File list; Show hidden files and folders
+..  index:: File list; Show hidden files and folders
+
+..  _user-setup-showHiddenFilesAndFolders:
 
 showHiddenFilesAndFolders
-=========================
+-------------------------
 
-:aspect:`Datatype`
-    boolean
+..  confval:: showHiddenFilesAndFolders
+    :name: user-setup-showHiddenFilesAndFolders
+    :type: boolean
 
-:aspect:`Description`
     If set, hidden files and folders will be shown in the filelist.
 
 
-.. index:: Start module
+..  index:: Start module
+
+..  _user-setup-startModule:
 
 startModule
-===========
+-----------
 
-:aspect:`Datatype`
-    string
+..  confval:: startModule
+    :name: user-setup-startModule
+    :type: string
 
-:aspect:`Description`
     Name of the module that is called when the user logs into the backend, for
     example `web_layout`, `web_list`, `web_view`, `web_info`, `web_ts` etc.
 
 
-.. index:: Title length, max
+..  index:: Title length, max
+
+..  _user-setup-titleLen:
 
 titleLen
-========
+--------
 
-:aspect:`Datatype`
-    positive integer
+..  confval:: titleLen
+    :name: user-setup-titleLen
+    :type: positive integer
 
-:aspect:`Description`
     Maximum length of rendered record titles in the backend interface.
     It is used in several places: page tree, edit masks, workspace module, etc.
 
-    .. tip::
+    ..  tip::
         To find out where this setting is applied, set it to a low number.
diff --git a/Documentation/TSconfig/Documentation/UserTsconfig/_Setup/_user-setup-default.tsconfig b/Documentation/TSconfig/Documentation/UserTsconfig/_Setup/_user-setup-default.tsconfig
@@ -0,0 +1,20 @@
+[backend.user.isAdmin]
+    # Some settings an administrator might find helpful
+    setup.default {
+        recursiveDelete = 1
+        copyLevels = 99
+        moduleData {
+            # Defaulting some options of the Template/TypoScript backend module
+            web_ts {
+                # Pre-select 'Object browser' instead of 'Constant editor'
+                function = TYPO3\CMS\Tstemplate\Controller\TypoScriptTemplateObjectBrowserModuleFunctionController
+                # Pre-select 'Setup' instead of 'Constants'
+                ts_browser_type = setup
+                # The other settings
+                ts_browser_const = subst
+                ts_browser_fixedLgd = 0
+                ts_browser_showComments = 1
+            }
+        }
+    }
+[END]