From c329f20eba2f3aa0fe45ca66f9682e02856a1362 Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Mon, 22 Apr 2024 19:26:06 +0200 Subject: [PATCH] [TASK] Split up TCEFORM It has become quite long and hard to handle. No text changes where made releases: main, 12.4 --- Documentation/PageTsconfig/TceForm.rst | 371 +----------------- .../TceForm/ApplyingProperties.rst | 49 +++ .../PageTsconfig/TceForm/Suggest.rst | 325 +++++++++++++++ 3 files changed, 380 insertions(+), 365 deletions(-) create mode 100644 Documentation/PageTsconfig/TceForm/ApplyingProperties.rst create mode 100644 Documentation/PageTsconfig/TceForm/Suggest.rst diff --git a/Documentation/PageTsconfig/TceForm.rst b/Documentation/PageTsconfig/TceForm.rst index 700bf06..bd2b61c 100644 --- a/Documentation/PageTsconfig/TceForm.rst +++ b/Documentation/PageTsconfig/TceForm.rst @@ -17,54 +17,6 @@ disable options, blind options in selector boxes etc. See the core API document section :ref:`FormEngine ` for more details on how records are rendered in the backend. -.. _tceform-apply-properties: - -Applying properties -=================== - -The properties listed below apply to various contexts which are explained per -property. The full property path thus depends on the property and where it should -apply. In general, a more specific property path overrides a less specific one: - -Some properties apply to single fields, those can be usually set per table or -per table and record type. This leads to the property paths -`TCEFORM.[tableName].[fieldName].[propertyName]` to configure the field for all types -and `TCEFORM.[tableName].[fieldName].types.[typeName]` to configure a field for a specific -type, see the :ref:`TCA type section ` for details on types. - -While all that property path munging looks messy at first, it should become more -clear when reading through the single properties below and looking at the examples. - -.. youtube:: B3IQq7pIJ_o - -.. _tceformApplyPropertiesFlexForm: - -Applying properties to FlexForm fields --------------------------------------- - -Other properties also apply to :ref:`FlexForm ` fields, in this case the full property -path including the data structure key has to be set: - -.. code-block:: typoscript - - # TCEFORM.[tableName].[fieldName].[dataStructureKey].[flexSheet].[flexFieldName with escaped dots].[propertyName] - TCEFORM.tt_content.pi_flexform.sfregister_create.sDEF.settings\.fields\.selected.addItems.ZZZ = ZZZ - -The sheet name (sDEF) must be given only if the FlexForm has a sheet. - -The `[dataStructureKey]` represents the key of a FlexForm in -:php:`$GLOBALS['TCA'][]['columns'][]['config']['ds']`. This key will be split into up to -two parts. By default the first part will be used as identifier of the FlexForm in TSconfig. The second part -will override the identifier if it is not empty, `list` or `*`. For example the identifier of the key -`myext_pi1,list` will be `myext_pi1` and of the key `*,my_CType` it will be `my_CType`. See section -:ref:`Pointing to a data structure ` of the TCA reference for details. - -The flexFieldName is the name of the property in the FlexForm. If it contains -dots ('.'), these must be escaped with backslash. - -Some properties apply to whole FlexForm sheets, their property path is -`TCEFORM.[tableName].[fieldName].[dataStructureKey].[flexSheet].[propertyName]`. - .. _tceform-properties: Properties @@ -940,326 +892,15 @@ Example: Rename the first tab of the FlexForm plugin sheetTitle = LLL:my_ext/Resource/Private/Language/locallang.xlf:tt_content.pi_flexform.myext_pi1.sDEF } -.. index:: - Records; Suggest wizard - Suggest wizard -.. _pagetceformsuggest: - suggest ------- Configuration of the suggest wizard that is available and often enabled -for :ref:`TCA type=group ` fields. - -.. figure:: /Images/ManualScreenshots/List/TcaTypeGroupSuggest.png - :alt: A configured suggest wizard - - A configured suggest wizard - -The properties listed below are available on various levels. A more specific setting overrides -a less specific one: - -Configuration of all suggest wizards in all tables for all target query tables: - `TCEFORM.suggest.default` - -Configuration of all suggest wizards in all tables looking up records from a specific target table: - `TCEFORM.suggest.[queryTable]` - -Configuration of one suggest wizard field in one table for all target query tables: - `TCEFORM.[tableName].[fieldName].suggest.default` - -Configuration of one suggest wizard field in one table for a specific target query table: - `TCEFORM.[tableName].[fieldName].suggest.[queryTable]` - -Configuration of one suggest wizard field in a flex form field of one table for all target query tables: - `TCEFORM.[tableName].[fieldName].[dataStructureKey].[sheetName].[flexFieldName].suggest.default` - -Configuration of one suggest wizard field in a flex form field of one table for a specific target query table: - `TCEFORM.[tableName].[fieldName].[dataStructureKey].[sheetName].[flexFieldName].suggest.[queryTable]` - -.. index:: - Suggest wizard; Search fields additional -.. _tceform-suggest-additionalSearchFields: - -suggest.additionalSearchFields -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. confval:: suggest.additionalSearchFields - :name: tceform-suggest-additionalSearchFields - :type: string - - Comma-separated list of fields the suggest wizard should also search in. By default the wizard looks only in the - fields listed in the :ref:`label ` and :ref:`label_alt ` - of TCA :ref:`ctrl properties `. - - -.. index:: - Suggest wizard; Where statement -.. _tceform-suggest-addWhere: - -suggest.addWhere -~~~~~~~~~~~~~~~~ - -.. confval:: suggest.addWhere - :name: tceform-suggest-addWhere - :type: string - - Additional WHERE clause (with AND at the beginning). - - Markers possible for replacement: - - * ###THIS_UID### - * ###CURRENT_PID### - * :ref:`###PAGE_TSCONFIG_ID### ` - * :ref:`###PAGE_TSCONFIG_IDLIST### ` - * :ref:`###PAGE_TSCONFIG_STR### ` - -.. _tceform-suggest-addWhere-example: - -Example: limit storage_pid to the children of a certain page -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: typoscript - :caption: EXT:site_package/Configuration/page.tsconfig - - TCEFORM.pages.storage_pid.suggest.default { - addWhere = AND pages.pid=###PAGE_TSCONFIG_ID### - } - -.. index:: - Suggest wizard; CSS class -.. _tceform-suggest-cssClass: - -suggest.cssClass -~~~~~~~~~~~~~~~~ - -.. confval:: suggest.cssClass - :name: tceform-suggest-cssClass - :type: string - - Add a CSS class to every list item of the result list. - - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/page.tsconfig - - TCEFORM.suggest.pages { - # Configure all suggest wizards which list records from table "pages" - # to add the CSS class "pages" to every list item of the result list. - cssClass = pages - } - - -.. index:: - Suggest wizard; hide -.. _tceform-suggest-hide: - -suggest.hide -~~~~~~~~~~~~ - -.. confval:: suggest.hide - :name: tceform-suggest-hide - :type: boolean - - Hide the suggest field. Works only for single fields. - -.. _tceform-suggest-hide-example: - -Example: Hide the suggest field for the storage_pid -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: typoscript - :caption: EXT:site_package/Configuration/page.tsconfig - - TCEFORM.pages.storage_pid.suggest.default { - hide = 1 - } - - -.. index:: - Suggest wizard; Characters max -.. _tceform-suggest-maxPathTitleLength: - -suggest.maxPathTitleLength -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. confval:: suggest.maxPathTitleLength - :name: tceform-suggest-maxPathTitleLength - :type: positive integer - - Maximum number of characters to display when a path element is too long. - -.. _tceform-suggest-maxPathTitleLength-example: +for :ref:`TCA type=group ` fields. See +:ref:`property suggest ` for more information. -Example: Limit the suggest field to 30 characters -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. toctree:: + :glob: + :hidden: -.. code-block:: typoscript - :caption: EXT:site_package/Configuration/page.tsconfig - - TCEFORM.suggest.default { - maxPathTitleLength = 30 - } - -.. index:: - Suggest wizard; Characters min -.. _tceform-suggest-minimumCharacters: - -suggest.minimumCharacters -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. confval:: suggest.minimumCharacters - :name: tceform-suggest-minimumCharacters - :type: positive integer - :Default: 2 - - Minimum number of characters needed to start the search. Works only for single fields. - -.. _tceform-suggest-minimumCharacters-example: - -Example: Start the suggest search after 3 characters -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: typoscript - :caption: EXT:site_package/Configuration/page.tsconfig - - TCEFORM.pages.storage_pid.suggest.default { - minimumCharacters = 3 - } - - -.. index:: - Suggest wizard; pid levels -.. _tceform-suggest-pidDepth: - -suggest.pidDepth -~~~~~~~~~~~~~~~~ - -.. confval:: suggest.pidDepth - :name: tceform-suggest-pidDepth - :type: positive integer - - Expand pidList by this number of levels. Only has an effect, if pidList has a value. - -.. _tceform-suggest-pidDepth-example: - -Example: Set search depth for suggest field -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: typoscript - :caption: EXT:site_package/Configuration/page.tsconfig - - TCEFORM.suggest.default { - pidList = 6,7 - pidDepth = 4 - } - -.. index:: - Suggest wizard; pid list -.. _tceform-suggest-pidList: - -suggest.pidList -~~~~~~~~~~~~~~~ - -.. confval:: suggest.pidList - :name: tceform-suggest-pidList - :type: list of values - - Limit the search to certain pages (and their subpages). When pidList is empty all pages will be included - in the search as long as the backend user is allowed to see them. - -.. _tceform-suggest-pidList-example: - -Example: Limit suggest search to records on certain pages -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: typoscript - :caption: EXT:site_package/Configuration/page.tsconfig - - TCEFORM.suggest.default { - # sets the pidList for a suggest fields in all tables - pidList = 1,2,3,45 - } - - -.. index:: - Suggest wizard; receiver php class -.. _tceform-suggest-receiverClass: - -suggest.receiverClass -~~~~~~~~~~~~~~~~~~~~~ - -.. confval:: suggest.receiverClass - :name: tceform-suggest-receiverClass - :type: Fully Qualified PHP class name - :Default: :php:`\TYPO3\CMS\Backend\Form\Element\SuggestDefaultReceiver` - - PHP class alternative receiver class - the file that holds the class should be derived - from :code:`\TYPO3\CMS\Backend\Form\Element\SuggestDefaultReceiver`. - -.. index:: - Suggest wizard; rendering user function -.. _tceform-suggest-renderFunc: - -suggest.renderFunc -~~~~~~~~~~~~~~~~~~ - -.. confval:: suggest.renderFunc - :name: tceform-suggest-renderFunc - :type: string - - User function to manipulate the displayed records in the result. - -.. index:: - Suggest wizard; Where statement -.. _tceform-suggest-searchCondition: - -suggest.searchCondition -~~~~~~~~~~~~~~~~~~~~~~~ - -.. confval:: suggest.searchCondition - :name: tceform-suggest-searchCondition - :type: string - - Additional WHERE clause (no AND needed to prepend). - -.. _tceform-suggest-searchCondition-example: - -Example: Only search on pages with doktype=1 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - .. code-block:: typoscript - :caption: EXT:site_package/Configuration/page.tsconfig - - TCEFORM.pages.storage_pid.suggest.default { - # Configure the suggest wizard for the field "storage_pid" in table "pages" - # to search only for pages with doktype=1 - searchCondition = doktype=1 - } - -.. index:: - Suggest wizard; Search whole phrase -.. _tceform-suggest-searchWholePhrase: - -suggest.searchWholePhrase -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. confval:: suggest.searchWholePhrase - :name: tceform-suggest-searchWholePhrase - :type: boolean - :Default: 0 - - Whether to do a `LIKE=%mystring%` (searchWholePhrase = 1) or a - `LIKE=mystring%` (to do a real find as you type). - -.. _tceform-suggest-searchWholePhrase-example: - -Example: Search only for whole phrases -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: typoscript - :caption: EXT:site_package/Configuration/page.tsconfig - - TCEFORM.pages.storage_pid.suggest.default { - # Configure the suggest wizard for the field "storage_pid" in table "pages" to search only for whole phrases - searchWholePhrase = 1 - } + TceForm/* diff --git a/Documentation/PageTsconfig/TceForm/ApplyingProperties.rst b/Documentation/PageTsconfig/TceForm/ApplyingProperties.rst new file mode 100644 index 0000000..aa17db7 --- /dev/null +++ b/Documentation/PageTsconfig/TceForm/ApplyingProperties.rst @@ -0,0 +1,49 @@ +.. include:: /Includes.rst.txt +.. _tceform-apply-properties: + +=================== +Applying properties +=================== + +The properties listed below apply to various contexts which are explained per +property. The full property path thus depends on the property and where it should +apply. In general, a more specific property path overrides a less specific one: + +Some properties apply to single fields, those can be usually set per table or +per table and record type. This leads to the property paths +`TCEFORM.[tableName].[fieldName].[propertyName]` to configure the field for all types +and `TCEFORM.[tableName].[fieldName].types.[typeName]` to configure a field for a specific +type, see the :ref:`TCA type section ` for details on types. + +While all that property path munging looks messy at first, it should become more +clear when reading through the single properties below and looking at the examples. + +.. youtube:: B3IQq7pIJ_o + +.. _tceformApplyPropertiesFlexForm: + +Applying properties to FlexForm fields +====================================== + +Other properties also apply to :ref:`FlexForm ` fields, in this case the full property +path including the data structure key has to be set: + +.. code-block:: typoscript + + # TCEFORM.[tableName].[fieldName].[dataStructureKey].[flexSheet].[flexFieldName with escaped dots].[propertyName] + TCEFORM.tt_content.pi_flexform.sfregister_create.sDEF.settings\.fields\.selected.addItems.ZZZ = ZZZ + +The sheet name (sDEF) must be given only if the FlexForm has a sheet. + +The `[dataStructureKey]` represents the key of a FlexForm in +:php:`$GLOBALS['TCA'][]['columns'][]['config']['ds']`. This key will be split into up to +two parts. By default the first part will be used as identifier of the FlexForm in TSconfig. The second part +will override the identifier if it is not empty, `list` or `*`. For example the identifier of the key +`myext_pi1,list` will be `myext_pi1` and of the key `*,my_CType` it will be `my_CType`. See section +:ref:`Pointing to a data structure ` of the TCA reference for details. + +The flexFieldName is the name of the property in the FlexForm. If it contains +dots ('.'), these must be escaped with backslash. + +Some properties apply to whole FlexForm sheets, their property path is +`TCEFORM.[tableName].[fieldName].[dataStructureKey].[flexSheet].[propertyName]`. diff --git a/Documentation/PageTsconfig/TceForm/Suggest.rst b/Documentation/PageTsconfig/TceForm/Suggest.rst new file mode 100644 index 0000000..42cfc1b --- /dev/null +++ b/Documentation/PageTsconfig/TceForm/Suggest.rst @@ -0,0 +1,325 @@ +.. include:: /Includes.rst.txt +.. index:: + Records; Suggest wizard + Suggest wizard +.. _pagetceformsuggest: + +======= +suggest +======= + +Configuration of the suggest wizard that is available and often enabled +for :ref:`TCA type=group ` fields. + +.. figure:: /Images/ManualScreenshots/List/TcaTypeGroupSuggest.png + :alt: A configured suggest wizard + + A configured suggest wizard + +The properties listed below are available on various levels. A more specific setting overrides +a less specific one: + +Configuration of all suggest wizards in all tables for all target query tables: + `TCEFORM.suggest.default` + +Configuration of all suggest wizards in all tables looking up records from a specific target table: + `TCEFORM.suggest.[queryTable]` + +Configuration of one suggest wizard field in one table for all target query tables: + `TCEFORM.[tableName].[fieldName].suggest.default` + +Configuration of one suggest wizard field in one table for a specific target query table: + `TCEFORM.[tableName].[fieldName].suggest.[queryTable]` + +Configuration of one suggest wizard field in a flex form field of one table for all target query tables: + `TCEFORM.[tableName].[fieldName].[dataStructureKey].[sheetName].[flexFieldName].suggest.default` + +Configuration of one suggest wizard field in a flex form field of one table for a specific target query table: + `TCEFORM.[tableName].[fieldName].[dataStructureKey].[sheetName].[flexFieldName].suggest.[queryTable]` + +.. index:: + Suggest wizard; Search fields additional +.. _tceform-suggest-additionalSearchFields: + +suggest.additionalSearchFields +============================== + +.. confval:: suggest.additionalSearchFields + :name: tceform-suggest-additionalSearchFields + :type: string + + Comma-separated list of fields the suggest wizard should also search in. By default the wizard looks only in the + fields listed in the :ref:`label ` and :ref:`label_alt ` + of TCA :ref:`ctrl properties `. + + +.. index:: + Suggest wizard; Where statement +.. _tceform-suggest-addWhere: + +suggest.addWhere +================ + +.. confval:: suggest.addWhere + :name: tceform-suggest-addWhere + :type: string + + Additional WHERE clause (with AND at the beginning). + + Markers possible for replacement: + + * ###THIS_UID### + * ###CURRENT_PID### + * :ref:`###PAGE_TSCONFIG_ID### ` + * :ref:`###PAGE_TSCONFIG_IDLIST### ` + * :ref:`###PAGE_TSCONFIG_STR### ` + +.. _tceform-suggest-addWhere-example: + +Example: limit storage_pid to the children of a certain page +------------------------------------------------------------ + +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/page.tsconfig + + TCEFORM.pages.storage_pid.suggest.default { + addWhere = AND pages.pid=###PAGE_TSCONFIG_ID### + } + +.. index:: + Suggest wizard; CSS class +.. _tceform-suggest-cssClass: + +suggest.cssClass +================ + +.. confval:: suggest.cssClass + :name: tceform-suggest-cssClass + :type: string + + Add a CSS class to every list item of the result list. + + .. code-block:: typoscript + :caption: EXT:site_package/Configuration/page.tsconfig + + TCEFORM.suggest.pages { + # Configure all suggest wizards which list records from table "pages" + # to add the CSS class "pages" to every list item of the result list. + cssClass = pages + } + + +.. index:: + Suggest wizard; hide +.. _tceform-suggest-hide: + +suggest.hide +============ + +.. confval:: suggest.hide + :name: tceform-suggest-hide + :type: boolean + + Hide the suggest field. Works only for single fields. + +.. _tceform-suggest-hide-example: + +Example: Hide the suggest field for the storage_pid +--------------------------------------------------- + +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/page.tsconfig + + TCEFORM.pages.storage_pid.suggest.default { + hide = 1 + } + + +.. index:: + Suggest wizard; Characters max +.. _tceform-suggest-maxPathTitleLength: + +suggest.maxPathTitleLength +========================== + +.. confval:: suggest.maxPathTitleLength + :name: tceform-suggest-maxPathTitleLength + :type: positive integer + + Maximum number of characters to display when a path element is too long. + +.. _tceform-suggest-maxPathTitleLength-example: + +Example: Limit the suggest field to 30 characters +-------------------------------------------------- + +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/page.tsconfig + + TCEFORM.suggest.default { + maxPathTitleLength = 30 + } + +.. index:: + Suggest wizard; Characters min +.. _tceform-suggest-minimumCharacters: + +suggest.minimumCharacters +========================= + +.. confval:: suggest.minimumCharacters + :name: tceform-suggest-minimumCharacters + :type: positive integer + :Default: 2 + + Minimum number of characters needed to start the search. Works only for single fields. + +.. _tceform-suggest-minimumCharacters-example: + +Example: Start the suggest search after 3 characters +----------------------------------------------------- + +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/page.tsconfig + + TCEFORM.pages.storage_pid.suggest.default { + minimumCharacters = 3 + } + + +.. index:: + Suggest wizard; pid levels +.. _tceform-suggest-pidDepth: + +suggest.pidDepth +================ + +.. confval:: suggest.pidDepth + :name: tceform-suggest-pidDepth + :type: positive integer + + Expand pidList by this number of levels. Only has an effect, if pidList has a value. + +.. _tceform-suggest-pidDepth-example: + +Example: Set search depth for suggest field +-------------------------------------------- + +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/page.tsconfig + + TCEFORM.suggest.default { + pidList = 6,7 + pidDepth = 4 + } + +.. index:: + Suggest wizard; pid list +.. _tceform-suggest-pidList: + +suggest.pidList +=============== + +.. confval:: suggest.pidList + :name: tceform-suggest-pidList + :type: list of values + + Limit the search to certain pages (and their subpages). When pidList is empty all pages will be included + in the search as long as the backend user is allowed to see them. + +.. _tceform-suggest-pidList-example: + +Example: Limit suggest search to records on certain pages +--------------------------------------------------------- + +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/page.tsconfig + + TCEFORM.suggest.default { + # sets the pidList for a suggest fields in all tables + pidList = 1,2,3,45 + } + + +.. index:: + Suggest wizard; receiver php class +.. _tceform-suggest-receiverClass: + +suggest.receiverClass +===================== + +.. confval:: suggest.receiverClass + :name: tceform-suggest-receiverClass + :type: Fully Qualified PHP class name + :Default: :php:`\TYPO3\CMS\Backend\Form\Element\SuggestDefaultReceiver` + + PHP class alternative receiver class - the file that holds the class should be derived + from :code:`\TYPO3\CMS\Backend\Form\Element\SuggestDefaultReceiver`. + +.. index:: + Suggest wizard; rendering user function +.. _tceform-suggest-renderFunc: + +suggest.renderFunc +================== + +.. confval:: suggest.renderFunc + :name: tceform-suggest-renderFunc + :type: string + + User function to manipulate the displayed records in the result. + +.. index:: + Suggest wizard; Where statement +.. _tceform-suggest-searchCondition: + +suggest.searchCondition +======================= + +.. confval:: + :name: tceform-suggest-searchCondition + :type: string + + Additional WHERE clause (no AND needed to prepend). + +.. _tceform-suggest-searchCondition-example: + +Example: Only search on pages with doktype=1 +---------------------------------------------- + + .. code-block:: typoscript + :caption: EXT:site_package/Configuration/page.tsconfig + + TCEFORM.pages.storage_pid.suggest.default { + # Configure the suggest wizard for the field "storage_pid" in table "pages" + # to search only for pages with doktype=1 + searchCondition = doktype=1 + } + +.. index:: + Suggest wizard; Search whole phrase +.. _tceform-suggest-searchWholePhrase: + +suggest.searchWholePhrase +========================= + +.. confval:: suggest.searchWholePhrase + :name: tceform-suggest-searchWholePhrase + :type: boolean + :Default: 0 + + Whether to do a `LIKE=%mystring%` (searchWholePhrase = 1) or a + `LIKE=mystring%` (to do a real find as you type). + +.. _tceform-suggest-searchWholePhrase-example: + +Example: Search only for whole phrases +---------------------------------------- + +.. code-block:: typoscript + :caption: EXT:site_package/Configuration/page.tsconfig + + TCEFORM.pages.storage_pid.suggest.default { + # Configure the suggest wizard for the field "storage_pid" in table "pages" to search only for whole phrases + searchWholePhrase = 1 + }