[TASK] Merge properties to select multiple side by side (#1143)

Releases: main, 12.4

Documentation/ColumnsConfig/Type/Select/MultipleSideBySide/Examples.rst

@@ -1,17 +1,14 @@
-..  include:: /Includes.rst.txt
-
-========
-Examples
-========
+:navigation-title: Examples
 
-..  _tca_example_select_multiplesidebyside_1:
+..  include:: /Includes.rst.txt
 
-Simple side-by-side select field
-================================
+..  _columns-select-rendertype-selectMultipleSideBySide-examples:
 
-..  include:: /Images/Rst/SelectMultiplesidebyside1.rst.txt
+========================================================
+Advanced examples for multiple side-by-side select boxes
+========================================================
 
-..  include:: /CodeSnippets/SelectMultiplesidebyside1.rst.txt
+See also: `tca_example_select_multiplesidebyside_1`.
 
 ..  _tca_example_select_multiplesidebyside_5:
 

Documentation/ColumnsConfig/Type/Select/MultipleSideBySide/Index.rst

@@ -12,10 +12,20 @@ This page describes the :ref:`select <columns-select>` type with
 It displays two select fields. The items can be selected from the right field.
 All selected items are displayed in the left field.
 
-..  include:: /Images/Rst/SelectMultiplesidebyside1.rst.txt
+..  contents:: Table of contents
 
 ..  toctree::
     :titlesonly:
 
     Examples
-    Properties
+
+..  _tca_example_select_multiplesidebyside_1:
+
+Example: Basic side-by-side select field
+================================
+
+..  include:: /Images/Rst/SelectMultiplesidebyside1.rst.txt
+
+..  include:: /CodeSnippets/SelectMultiplesidebyside1.rst.txt
+
+For more examples see also :ref:`columns-select-rendertype-selectMultipleSideBySide-examples`.

Documentation/ColumnsConfig/Type/Select/MultipleSideBySide/_Properties/_AllowNonIdValues.rst.txt

@@ -0,0 +1,17 @@
+..  confval:: allowNonIdValues
+    :name: select-byside-allowNonIdValues
+    :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
+    :type: boolean
+    :Scope: Proc.
+    :RenderType: all
+
+    Only useful if :confval:`select-byside-foreign-table` is enabled.
+
+    If set, then values which are not integer ids will be allowed. May be needed
+    if you use itemsProcFunc or just enter additional items in the items array
+    to produce some string-value elements for the list.
+
+    ..  note::
+        If you mix non-database relations with database relations like this, DO
+        NOT use integers for values and DO NOT use "\_" (underscore) in values
+        either! Will not work if you also use "MM" relations!

Documentation/ColumnsConfig/Type/Select/MultipleSideBySide/_Properties/_AuthMode.rst.txt

@@ -0,0 +1,34 @@
+..  _columns-select-byside-properties-authmode:
+
+..  confval:: authMode
+    :name: select-byside-authMode
+    :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
+    :type: string (keyword)
+    :Scope: Display  / Proc.
+    :RenderType: all
+
+    ..  versionchanged:: 12.0
+        The only valid value for TCA config option :php:`authMode` is now :php:`explicitAllow`.
+        The values :php:`explicitDeny` and :php:`individual` are obsolete and no longer evaluated.
+
+    Authorization mode for the selector box. The only possible option is:
+
+    explicitAllow
+        All static values from the "items" array of the selector box will be added to a matrix in the backend user
+        configuration where a value must be explicitly selected if a user (other than admin) is allowed to use it!)
+
+..  rubric:: Migration: Using authMode='explicitDeny'
+
+The "deny list" approach for single field values has been removed, the only allowed option
+for :php:`authMode` is :php:`explicitAllow`. Extensions using config value :php:`explicitDeny`
+should be adapted to switch to :php:`explicitAllow` instead. The upgrade wizard
+"Migrate backend groups "explicit_allowdeny" field to simplified format." that transfers
+existing :sql:`be_groups` rows to the new format, **drops** any :sql:`DENY` fields and instructs
+admins to not set new access rights of affected backend groups.
+
+..  rubric:: Migration: Using authMode='individual'
+
+Handling of :php:`authMode` being set to :php:`individual` has been fully dropped.
+The Core provides no alternative. This has been an obscure setting ever since and there is no
+direct migration. Extensions that rely on this handling need to find a substitution based on
+Core hooks, Core events or other existing Core API functionality.

Documentation/ColumnsConfig/Type/Select/MultipleSideBySide/_Properties/_AuthModeEnforce.rst.txt

@@ -0,0 +1,17 @@
+
+..  _columns-select-byside-properties-authmode-enforce:
+
+..  versionchanged:: 12.0
+    Handling of TCA config option :php:`authMode_enforce` has been removed.
+
+Migration: Using authMode_enforce='strict'
+
+Extensions with select fields using :php:`authMode` previously had different handling
+if :php:`authMode_enforce => 'strict'` has been set: Let us say an editor accesses a record
+with an :php:`authMode` field being set to a value it has no access to. With :php:`authMode_enforce`
+**not** being set to :php:`strict`, the editor was still able to edit the record and set the value
+to something it had access to. With :php:`authMode_enforce` being set to :php:`strict`, the editor
+was not allowed to access the record. This has been streamlined: The backend interface no longer
+renders those records for the editor and an "access denied" message is rendered instead. To
+prevent this, a group this editor is member of needs to be adapted to allow access to this
+particular value in the "Explicitly allow field values" (:sql:`explicit_allowdeny`) field.

Documentation/ColumnsConfig/Type/Select/MultipleSideBySide/_Properties/_AutoSizeMax.rst.txt

@@ -0,0 +1,17 @@
+
+..  confval:: autoSizeMax
+    :name: select-byside-autoSizeMax
+    :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
+    :type: integer
+    :Scope: Display
+
+    The maximum size (height) of the select field.
+
+    The size of the select field will be automatically adjusted based on
+    the number of selected items. The select field will never be smaller than
+    the specified :confval:`size <select-byside-size>` and never larger than
+    the value of `autoSizeMax`.
+
+    ..  note::
+        Only has an effect if :confval:`maxitems <select-byside-maxitems>` is
+        greater than 1.

Documentation/ColumnsConfig/Type/Select/MultipleSideBySide/_Properties/_Behaviour.rst.txt

@@ -0,0 +1,23 @@
+..  confval:: behaviour
+    :name: select-byside-behaviour
+
+    ..  confval:: allowLanguageSynchronization
+        :type: boolean
+        :name: select-byside-behaviour-allowLanguageSynchronization
+        :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['behaviour']['allowLanguageSynchronization']
+        :Scope: Proc.
+        :default: false
+
+        Allows an editor to select in a localized record whether the value is copied
+        over from default or source language record, or if the field has an own value
+        in the localization. If set to true and if the table supports localization
+        and if a localized record is edited, this setting enables FieldWizard
+        :ref:`LocalizationStateSelector <columns-input-properties-fieldWizard-localizationStateSelector>`:
+        Two or three radio buttons shown below the field input. The state of this is
+        stored in a json encoded array in the database table called :code:`l10n_state`.
+        It tells the DataHandler which fields of the localization records should be kept
+        in sync if the underlying default or source record changes.
+
+        ..  literalinclude:: _Snippets/_AllowLanguageSynchronization.php
+            :caption: EXT:my_extension/Configuration/TCA/Overrides/someTable.php
+

Documentation/ColumnsConfig/Type/Select/MultipleSideBySide/_Properties/_DbFieldLength.rst.txt

@@ -0,0 +1,25 @@
+
+..  confval:: dbFieldLength
+    :name: select-byside-dbFieldLength
+    :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
+    :type: integer
+    :Default: 255
+    :Scope: Proc.
+
+    ..  versionadded:: 13.0
+        As TYPO3 takes care of
+        :ref:`generating the according database field <t3coreapi:auto-generated-db-structure>`
+        for `select` fields since TYPO3 v13, a developer can adjust the length
+        of the database field with this option in TCA directly.
+
+    The TCA config option :php:`dbFieldLength` contains an integer value
+    that is applied to :sql:`varchar` fields (not :sql:`text`) and defines the
+    length of the database field. It will not be respected for fields that
+    resolve to an integer type. Developers who wish to optimize field length can
+    use :php:`dbFieldLength` for :php:`type=select` fields to increase or
+    decrease the default length.
+
+..  rubric:: Example: Increase the dbFieldLength for a select field
+
+..  literalinclude:: _Snippets/_DbFieldLength.php
+    :caption: Excerpt from EXT:my_extension/Configuration/TCA/myextension_domain_model_mytable.php

Documentation/ColumnsConfig/Type/Select/MultipleSideBySide/_Properties/_Default.rst.txt

@@ -0,0 +1,11 @@
+..  _columns-select-byside-properties-default:
+
+..  confval:: default
+    :name: select-byside-default
+    :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
+    :type: string
+    :Scope: Display  / Proc.
+    :RenderType: all
+
+    Default value set if a new record is created. If empty, the first element in
+    the items array is selected.

Documentation/ColumnsConfig/Type/Select/MultipleSideBySide/_Properties/_DisableNonMatchingValueElement.rst.txt

@@ -0,0 +1,12 @@
+..  _columns-select-byside-properties-disablenomatchingvalueelement:
+
+..  confval:: disableNoMatchingValueElement
+    :name: select-byside-disableNoMatchingValueElement
+    :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
+    :type: boolean
+    :Scope: Display
+    :RenderType: all
+
+    If set, then no element is inserted if the current value does not match
+    any of the existing elements. A corresponding options is also found in Page
+    TSconfig.

Documentation/ColumnsConfig/Type/Select/MultipleSideBySide/_Properties/_ExclusiveKeys.rst.txt

@@ -0,0 +1,9 @@
+
+..  confval:: exclusiveKeys
+    :name: select-byside-exclusiveKeys
+    :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
+    :type: string (list of)
+    :Scope: Display  / Proc.
+
+    List of keys that exclude any other keys in a select box where multiple
+    items could be selected.

Documentation/ColumnsConfig/Type/Select/MultipleSideBySide/_Properties/_FieldControl.rst.txt

@@ -0,0 +1,11 @@
+..  confval:: fieldControl
+    :name: select-byside-fieldControl
+
+    ..  include:: /ColumnsConfig/Type/Select/MultipleSideBySide/_Properties/_FieldControl/_AddRecord.rst.txt
+        :show-buttons:
+
+    ..  include:: /ColumnsConfig/Type/Select/MultipleSideBySide/_Properties/_FieldControl/_EditPopup.rst.txt
+        :show-buttons:
+
+    ..  include:: /ColumnsConfig/Type/Select/MultipleSideBySide/_Properties/_FieldControl/_ResetSelection.rst.txt
+        :show-buttons:

Documentation/ColumnsConfig/Type/Select/MultipleSideBySide/_Properties/_FieldControl/_AddRecord.rst.txt

@@ -0,0 +1,85 @@
+..  confval:: addRecord
+    :name: select-byside-fieldControl-addRecord
+    :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldControl']['addRecord']
+    :type: array
+    :Scope: fieldControl
+    :Types: :ref:`group <columns-group>`
+
+    Control button to directly add a related record. Leaves the current
+    view and opens a new form to add a new record. On 'Save and close', the
+    record is directly selected.
+
+    ..  note::
+        The add record control is disabled by default, enable it with
+        :confval:`select-byside-fieldControl-addRecord-disabled`.
+
+    ..  confval:: disabled
+        :name: select-byside-fieldControl-addRecord-disabled
+        :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldControl']['addRecord']
+        :type: boolean
+        :Scope: fieldControl -> addRecord
+        :Default: true
+
+        Disables the field control. Needs to be set to :php:`false` to enable the
+        :guilabel:`Create new` button
+
+    ..  confval:: options
+        :name: select-byside-fieldControl-addRecord-options
+        :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldControl']['addRecord']['options']
+
+        ..  confval:: pid
+            :name: select-byside-fieldControl-addRecord-options-pid
+            :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldControl']['addRecord']['options']['pid']
+            :type: string
+            :Scope: fieldControl -> addRecord
+            :Values: marker or an integer
+            :Default: ###CURRENT_PID###
+
+            pid of the new record. Can be an hard pid setting, or one of these markers,
+            see :ref:`select foreign_table_where
+            <columns-select-properties-foreign-table-where>`.
+
+            Falls back to "current pid" if not set, forces pid=0 if records of this
+            table are only allowed on root level.
+
+            -  :code:`###CURRENT_PID###`
+            -  :code:`###THIS_UID###`
+            -  :code:`###SITEROOT###`
+
+        ..  confval:: title
+            :name: select-byside-fieldControl-addRecord-options-title
+            :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldControl']['addRecord']['options']['title']
+            :type: string
+            :Values: string or LLL reference
+            :Default: LLL:EXT:lang/Resources/Private/Language/locallang_core.xlf:labels.createNew
+
+            Allows to set a different 'title' attribute to the popup icon.
+
+        ..  confval:: setValue
+            :name: select-byside-fieldControl-addRecord-options-setValue
+            :Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldControl']['addRecord']['options']['setValue']
+            :type: string
+            :Values: string
+            :Default: append
+
+            Can be one of 'set', 'prepend' or 'append'. With 'set' the given selection
+            is substituted with the new record, 'prepend' adds the new record on top of
+            the list, 'append' adds it at the bottom.
+
+..  _tca_example_select_multiplesidebyside_1:
+
+..  rubric:: Example: Multiple sidebyside select field with "Add record" enabled
+
+..  include:: /Images/Rst/SelectMultiplesidebyside1.rst.txt
+
+..  include:: /CodeSnippets/SelectMultiplesidebyside1.rst.txt
+
+..  rubric:: Example: Select field with options
+
+The field controls are also used in the core. The following example is from
+the table :sql:`be_groups`:
+
+..  include:: /Images/Rst/FileMountpoints.rst.txt
+
+..  include:: /CodeSnippets/FileMountpoints.rst.txt
+