[TASK] Overhaul Extension Development Howto Extend TCA (#6255)

* [TASK] Overhaul Extension Development Howto Extend TCA

Releases: main, Backport 13.4

* [TASK] Overhaul Extension Development Howto Extend TCA

Releases: main, Backport 13.4

Author: sarahmccarthy123

Documentation/ExtensionArchitecture/HowTo/ExtendingTca/Examples/Index.rst

@@ -5,8 +5,8 @@
 Customization Examples
 ======================
 
-Many extracts can be found throughout the manual, but this section
-provides more complete examples.
+There are many customization examples in the documentation, but this section
+provides the most complete examples.
 
 
 .. index::
@@ -18,7 +18,7 @@ Example 1: Extending the fe\_users table
 ========================================
 
 The "examples" extension adds two fields to the "fe\_users" table.
-Here's the complete code, taken from file
+Here is the complete code, taken from file
 :file:`Configuration/TCA/Overrides/fe_users.php`:
 
 .. code-block:: php
@@ -70,23 +70,22 @@ Read :ref:`why the check for the TYPO3 constant is necessary <globals-constants-
 
 .. note::
 
-   The second example :php:`tx_examples_special` only works when the
-   :php:`renderType` has been registered implemented and then registered in
-   the ext_localconf.php. Please refer to the the following chapter of the
-   TCA reference on how to implement it: :ref:`t3tca:columns-user`.
+   The second example, :php:`tx_examples_special`, only works when
+   :php:`renderType` has been registered, implemented, and registered in
+   ext_localconf.php. Please refer to :ref:`t3tca:columns-user`.
 
 
-In this example the first method call adds fields using
-:php:`ExtensionManagementUtility::addTCAcolumns()`. This ensures that the fields
-are registered in :php:`$GLOBALS['TCA']`. Parameters:
+The first method call adds fields using
+:php:`ExtensionManagementUtility::addTCAcolumns()`. This registers the fields
+in :php:`$GLOBALS['TCA']`. The parameters are:
 
 1. Name of the table to which the fields should be added.
-2. An array of the fields to be added. Each field is represented in the
+2. An array of the fields to be added. Each field is in
    :ref:`TCA syntax for columns <t3tca:columns>`.
 
-Since the fields are only registered but not used anywhere,  the fields are
-afterwards added to the "types" definition of the :sql:`fe_users` table by
-calling :php:`ExtensionManagementUtility::addToAllTCAtypes()`. Parameters:
+At this point the fields have been registered but not used anywhere, so they need to be added
+to the "types" definition of the :sql:`fe_users` table by
+calling :php:`ExtensionManagementUtility::addToAllTCAtypes()`. The parameters are:
 
 1.  Name of the table to which the fields should be added.
 2.  Comma-separated string of fields, the same syntax used in the
@@ -97,19 +96,19 @@ calling :php:`ExtensionManagementUtility::addToAllTCAtypes()`. Parameters:
     to an existing field (:php:`after:myfield`) or
     palette (:php:`after:palette:mypalette`).
 
-So you could do this:
+Example code:
 
 ..  literalinclude:: _fe_users.php
     :language: php
     :caption: EXT:some_extension/Configuration/TCA/Overrides/fe_users.php
 
-If the fourth parameter (position) is omitted or the specified field is not found,
-new fields are added at the bottom of the form. If the table uses tabs,
-new fields are added at the bottom of the :guilabel:`Extended` tab. This tab
+If the fourth parameter is omitted or the field is not found,
+new fields are added to the bottom of the form. If the table uses tabs,
+new fields are added to the bottom of the :guilabel:`Extended` tab. This tab
 is created automatically if it does not exist.
 
-These method calls do not create the corresponding fields in the database. The new
-fields must also be defined in the :file:`ext_tables.sql` file of the extension:
+These method calls do not create fields in the database. To do
+this, the new fields must be defined in the :file:`ext_tables.sql` file of the extension:
 
 .. code-block:: sql
    :caption: EXT:some_extension/ext_tables.sql
@@ -128,12 +127,12 @@ fields must also be defined in the :file:`ext_tables.sql` file of the extension:
    table already exists.
 
 
-The following screen shot shows the placement of the two
+The following screenshot shows the position of the two
 new fields when editing a "fe\_users" record:
 
 .. include:: /Images/AutomaticScreenshots/ExtendingTca/ExtendingTcaFeUsers.rst.txt
 
-The next example shows how to place a field more precisely.
+The next example shows how to position a field more precisely.
 
 
 .. index::
@@ -144,7 +143,7 @@ The next example shows how to place a field more precisely.
 Example 2: Extending the tt\_content Table
 ==========================================
 
-In the second example, we will add a "No print" field to all content
+In this second example, we will add a "No print" field to all content
 element types. First of all, we add its SQL definition in
 :file:`ext_tables.sql`:
 
@@ -186,16 +185,14 @@ Then we add it to the :php:`$GLOBALS['TCA']` in :file:`Configuration/TCA/Overrid
       'before:editlock'
    );
 
-The code is mostly the same as in the first example, but the last method call
-is different and requires an explanation. The tables :code:`pages` and
-:code:`tt_content` use :ref:`palettes <t3tca:palettes>` extensively. This increases
-flexibility.
-
-Therefore we call :code:`ExtensionManagementUtility::addFieldsToPalette()`
+The code is similar to the first example, but the last method call
+is different. The tables :code:`pages` and
+:code:`tt_content` use :ref:`palettes <t3tca:palettes>` extensively. Therefore,
+we call :code:`ExtensionManagementUtility::addFieldsToPalette()`
 instead of :code:`ExtensionManagementUtility::addToAllTCAtypes()`.
-We need to specify the palette's key as the second argument (:code:`access`).
-Precise placement of the new field is achieved with the fourth parameter
-(:code:`before:editlock`). This will place the "no print" field right before the
+We need to specify the palette key as the second argument (:code:`access`).
+The new field is positioned by the fourth parameter
+(:code:`before:editlock`). This will position the "no print" field before the
 :guilabel:`Restrict editing by non-Admins` field, instead of putting it in the
 :guilabel:`Extended` tab.
 
@@ -205,12 +202,11 @@ The result is the following:
 
 .. note::
 
-   Obviously this new field will not magically exclude a content element
-   from being printed. For it to have any effect, it must be used during
-   the rendering by modifying the TypoScript used to render the
-   :sql:`tt_content` table. Although this is outside the scope of this
+   Obviously this new field doesn't do anything yet. For it to do its job of
+   excluding a content element from being printed, it must modify the TypoScript
+   used to render the :sql:`tt_content` table. Although this is outside the scope of this
    manual, here is an example of what you could do, for the sake of
-   showing a complete process.
+   showing the complete process.
 
    Assuming you are using "fluid\_styled\_content" (which is installed by
    default), you could add the following TypoScript to your template:
@@ -225,6 +221,6 @@ The result is the following:
    be to declare the appropriate selector in the print-media CSS file so
    that "noprint" elements don't get displayed.
 
-   This is just an example of how the effect of the "No print" checkbox
-   can be ultimately implemented. It is meant to show that just adding
+   This is just an example of how the "No print" checkbox
+   can be implemented. It is meant to show that just adding
    the field to the :php:`$GLOBALS['TCA']` is not enough.

Documentation/ExtensionArchitecture/HowTo/ExtendingTca/Index.rst

@@ -1,4 +1,4 @@
-:navigation-title: TCA extension
+:navigation-title: Extend TCA
 
 .. include:: /Includes.rst.txt
 .. index::

Documentation/ExtensionArchitecture/HowTo/ExtendingTca/StoringChanges/Index.rst

@@ -3,49 +3,47 @@
 
 ..  _storing-changes:
 
-===================
-Storing the changes
-===================
+=====================
+Storing modifications
+=====================
 
-There are various ways to store changes to :php:`$GLOBALS['TCA']`. They
-depend - partly - on what you are trying to achieve and - a lot -
-on the version of TYPO3 CMS which you are targeting. The TCA can only be
-changed from within an extension.
+There are various ways to store modifications to :php:`$GLOBALS['TCA']`. They
+depend on what you are trying to achieve and the version of TYPO3 CMS you are
+targeting. The TCA can only be modified from inside an extension.
 
 
 ..  _storing-changes-extension:
 
 Storing in extensions
 =====================
 
-The advantage of putting your changes inside an extension is that they
-are nicely packaged in a self-contained entity which can be easily
-deployed on multiple servers.
+The advantage of putting modifications inside extensions is that the modifications
+are packaged in a self-contained entity that can be easily deployed.
 
-The drawback is that the extension loading order must be finely controlled. However, **in
-case you are modifying Core TCA, you usually don't have to worry about that**. Since
-custom extensions are always loaded *after* the Core's TCA, changes from custom extensions
-will usually take effect without any special measures.
+The drawback is that extension loading order must be finely controlled.
+**If you are modifying Core TCA, you usually don't have to worry about
+loading order**. Custom extensions are always loaded *after* the Core TCA, so
+modifications from custom extensions should always take effect.
 
 ..  attention::
-    If your extension modifies another extension, you actively need to make sure your
-    extension is loaded *after* the extension you are modifying. This can be achieved
-    by registering that other extension as a dependency (or suggestion) of yours. See
-    the :ref:`description of constraints in Core APIs <extension-declaration>`.
+    If your extension modifies another extension, make
+    sure your extension is loaded *after* the extension you are modifying. You can
+    do this by registering the other extension as a dependency (or suggestion)
+    of yours. See the :ref:`description of constraints in Core APIs <extension-declaration>`.
 
-    Loading order also matters if you have multiple extensions overriding the same field,
-    probably even contradicting each other.
+    Loading order also matters if you have multiple extensions overriding the
+    same field or contradicting each other.
 
 ..  versionadded:: 12.0
-    Files within :file:`Configuration/TCA/` files are loaded within a dedicated scope.
-    This means that variables defined in those files can't leak into the following files.
+    Files in :file:`Configuration/TCA/` are loaded inside a dedicated scope. This means
+    that variables defined in those files cannot leak into other files.
 
     ..  note::
         In TYPO3 v11 and below, variables declared in these files were in a shared scope,
         with the risk of a leakage to the following files. The use of :php:`call_user_func`
         wrap was a common workaround.
 
-For more information about an extension's structure, please refer to the
+For more information about extension structure, please refer to the
 :ref:`extension architecture <extension-architecture>` chapter.
 
 ..  index::
@@ -57,39 +55,39 @@ For more information about an extension's structure, please refer to the
 Storing in the :file:`Overrides/` folder
 ----------------------------------------
 
-Changes to :php:`$GLOBALS['TCA']`
-must be stored inside a folder called :file:`Configuration/TCA/Overrides/`.
-For clarity files should be named along the pattern
-:file:`<tablename>.php`.
+Modifications to :php:`$GLOBALS['TCA']`
+must be stored in :file:`Configuration/TCA/Overrides/`. For clarity, files should
+be named :file:`<tablename>.php`.
 
-Thus, if you want to customize the TCA of :sql:`tx_foo_domain_model_bar`,
-you need to create the file :file:`Configuration/TCA/Overrides/tx_foo_domain_model_bar.php`.
+For example, if you want to modify the TCA of :sql:`tx_foo_domain_model_bar`,
+create file :file:`Configuration/TCA/Overrides/tx_foo_domain_model_bar.php`.
 
-The advantage of this method is that all such changes are incorporated into
-:php:`$GLOBALS['TCA']` **before** it is cached. This is thus far more efficient.
+The advantage of this method is that changes will be incorporated into
+:php:`$GLOBALS['TCA']` **before** it is cached (which is very efficient).
 
 ..  note::
-    All files within :file:`Configuration/TCA/Overrides/` will be loaded, you are not forced
-    to have a single file for table "tt\_content" for instance. When dealing with custom
-    content elements this file can get 1000+ lines very quickly and maintainability can get
-    hard quickly as well.
-
-    Also names don't matter in that folder, at least not to TYPO3. They only might influence
-    loading order. Proper naming is only relevant for the real definition of tables one
+    All files in :file:`Configuration/TCA/Overrides/` will be loaded, so you can
+    divide up long files such as for table "tt\_content" rather than
+    having one long file. Otherwise, if you have custom
+    content elements this file can reach 1000+ lines very quickly, affecting
+    maintainability.
+
+    Also, names don't matter in this folder, at least not to TYPO3. They only influence
+    loading order. Proper naming is only relevant for the table definitions one
     folder up in :file:`Configuration/TCA/`
 
 ..  attention::
-    Be aware that you cannot extend the TCA of extensions if it was configured within
-    its :file:`ext_tables.php` file, usually containing the "ctrl" section
-    referencing a "dynamicConfigFile". Please ask the extension author to switch
+    You cannot extend the TCA of an extension if the modifications
+    are in its :file:`ext_tables.php` file (usually a "ctrl" section
+    referencing a "dynamicConfigFile"). Please ask the extension author to switch
     to the :file:`Configuration/TCA/<tablename>.php` setup.
 
 ..  attention::
-    Only TCA-related changes should go into :file:`Configuration/TCA/Overrides`
-    files. Some API calls may be okay as long as they also manipulate only
-    :php:`$GLOBALS['TCA']`. For example, it is fine to register a plugin with
+    Only TCA-related modifications should go in :file:`Configuration/TCA/Overrides`
+    files. Some API calls may be okay if all they do is manipulate
+    :php:`$GLOBALS['TCA']`. For example, a plugin can be registered with
     :php:`\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addPlugin()` in
-    :file:`Configuration/TCA/Overrides/tt_content.php` because that API call only
+    :file:`Configuration/TCA/Overrides/tt_content.php` because the API call only
     modifies :php:`$GLOBALS['TCA']` for table :sql:`tt_content`.
 
 ..  index::triple:PSR-14 event; TCA; AfterTcaCompilationEvent;
@@ -98,6 +96,6 @@ The advantage of this method is that all such changes are incorporated into
 Changing the TCA "on the fly"
 =============================
 
-It is also possible to perform some special manipulations on
-:php:`$GLOBALS['TCA']` right before it is stored into cache, thanks to the
+It is possible to manipulate
+:php:`$GLOBALS['TCA']` just before it is stored in the cache. Use the
 :ref:`PSR-14 event <EventDispatcher>` :ref:`AfterTcaCompilationEvent <AfterTcaCompilationEvent>`.

Documentation/ExtensionArchitecture/HowTo/ExtendingTca/Verifying/Index.rst

@@ -7,23 +7,22 @@
 =================
 Verifying the TCA
 =================
-You may find it necessary – at some point – to verify the full
-structure of the :php:`$GLOBALS['TCA']` in your TYPO3 installation.
-The :guilabel:`System > Configuration` module makes it possible to have an overview of the
-complete :php:`$GLOBALS['TCA']`, with all customizations taken into account.
+At some point it may be necessary to check the overall structure of
+:php:`$GLOBALS['TCA']` in your TYPO3 installation.
+The :guilabel:`System > Configuration` module gives you an overview of the
+complete :php:`$GLOBALS['TCA']`, with all modifications taken into account.
 
-.. note:: The :guilabel:`Configuration` module is part of the lowlevel system extension. In Composer mode
-   you can install it with:
+.. note::
+    The :guilabel:`Configuration` module is part of the lowlevel system extension. In Composer mode you can install it with:
 
    .. code-block:: shell
 
       composer req typo3/cms-lowlevel
 
 .. include:: /Images/AutomaticScreenshots/ExtendingTca/VerifyingTca.rst.txt
 
-If you cannot find your new field, it probably means that you have
-made some mistake.
+If you can't find your new field it probably means that you have
+made a mistake somewhere.
 
-This view is also useful when trying to find out where to insert a new
-field, to explore the combination of types and palettes that may be
-used for the table that we want to extend.
+The :guilabel:`System > Configuration` module overview is generally useful when you are extending TCA to find out where to insert
+fields and which types and palettes are used for a particular table.

Documentation/ExtensionArchitecture/HowTo/Index.rst

@@ -1,13 +1,13 @@
-:navigation-title: Howto
+:navigation-title: How-to
 
 .. include:: /Includes.rst.txt
 .. index::
    Extension development; How to
 .. _extension-howto:
 
-=====================================
-Howto guides for extension developers
-=====================================
+======================================
+How-to guides for extension developers
+======================================
 
 Helps you kickstart your own extension or site package. Explains how
 to publish an extension. Contains howto for different situations

Documentation/ExtensionArchitecture/Index.rst

@@ -39,7 +39,7 @@ Extension development
         Learn about tools to create a new extension or add
         functionality to an existing extension.
 
-    ..  card:: :ref:`Howto <extension-howto>`
+    ..  card:: :ref:`How-tos <extension-howto>`
 
         Kickstart your own extension or sitepackage. Explains how
         to publish an extension. Contains howtos for creating a frontend plugin,