[FEATURE] Extend chapter on content elements and plugins

- add introduction
- add chapter on creating plugins
- move chapter on flexforms into this chapter (menu only, URL and
  file location stays the same)
- refer to chapter on backend layouts
- add chapter "best practices"
- add t3datastructure to this chapter (menu only, URL and
  file location stays the same)
- remove menu item "Data Formats" from main menu

Documentation/ApiOverview/ContentElements/AddingYourOwnContentElements.rst

@@ -2,9 +2,9 @@
 
 .. _adding-your-own-content-elements:
 
-=======================
-Custom Content Elements
-=======================
+==============================
+Create Custom Content Elements
+==============================
 
 This page explains how to create your own custom content element types, in
 addition to the content elements already supplied by TYPO3. You can find

Documentation/ApiOverview/ContentElements/BestPractices.rst

@@ -0,0 +1,26 @@
+.. include:: ../../Includes.txt
+
+.. _best-practices:
+
+==============
+Best practices
+==============
+
+Following are some good practices for creating custom content element types and
+plugins and for customizing content elements for usage in the backend.
+
+* Use a sitepackage extension to maintain your site customization (such as
+  backend layouts, custom content elements etc.)
+* How you structure your extensions depends a little on the use case and if
+  they will be resused in several projects and / or made public. If you create one
+  extension for every custom content element, you may want to think about
+  whether they might be merged into one or more extensions.
+* Do not use deprecated functionality. Read the `Core Changelog <https://docs.typo3.org/c/typo3/cms-core/master/en-us/>`__
+  to check for deprecations and breaking changes between TYPO3 versions.
+* Some naming conventions are described in the chapter :ref:`extension-naming`.
+* Read (or skim) the :ref:`cgl`.
+* Make it easier for your editors by hiding the following by
+  :ref:`configuration <cePluginsCustomize>`
+
+  * content elements that should not be used in the "Content Element Wizard"
+  * fields that should not be filled out in the backend forms.

Documentation/ApiOverview/ContentElements/ContentElementsWizard.rst

@@ -2,9 +2,9 @@
 
 .. _content-element-wizard:
 
-=============================================
-Adding Elements to the Content Element Wizard
-=============================================
+==========================================
+Add Elements to the Content Element Wizard
+==========================================
 
 The content elements wizard is opened when a new element is
 created.

Documentation/ApiOverview/ContentElements/CreatePlugins.rst

@@ -0,0 +1,23 @@
+.. include:: ../../Includes.txt
+
+.. _create plugins:
+
+==============
+Create Plugins
+==============
+
+How to create plugins with the Extbase framework and Fluid templating engine is handled
+in depth in the chapter :ref:`t3extbasebook:configuring-the-plugin` in the "Extbase / Fluid book".
+
+There are basically two ways to create plugins in TYPO3:
+
+#. With the Extbase framework using :php:`configurePlugin()` in the file :file:`ext_localconf.php`
+   and :php:`registerPlugin()` in the file :file:`Configuration/TCA/Overrides/tt_content.php`
+#. Create a plugin using :php:`AbstractPlugin` **without** Extbase.
+
+Generally speaking, if you already use Extbase, it is good practice to create your plugins
+using the Extbase framework. This also involves:
+
+* creating controller actions
+* create a domain model and repository (if your plugin requires records that are persisted in the database)
+* create a view using Fluid templates

Documentation/ApiOverview/ContentElements/Index.rst

@@ -8,14 +8,10 @@
 Content Elements & Plugins
 ==========================
 
-.. todo:: add introductory text
-
-.. - add introductory text explaining content elements and plugins
-..   - difference between content elements & plugins
-.. - add additional chapters / link to existing docs
-..   - create your own content elements (from fluid_styled_content docs)
-..   - create plugins : Extbase / AbstractPlugin
+This chapter handles content elements & plugins: What they are, how they can be
+created, how existing content elements or plugins can be customized etc.
 
+**Table of Contents**
 
 :ref:`Some content elements <fsc:content-elements>` are supplied by the TYPO3
 system extension **fluid_styled_content**.
@@ -24,9 +20,13 @@ system extension **fluid_styled_content**.
 .. toctree::
    :maxdepth: 1
 
+   Introduction
    AddingYourOwnContentElements
+   CreatePlugins
    ContentElementsWizard
    ../FlexForms/Index
-
+   ../DataFormats/T3datastructure/Index
+   ../BackendLayout/Index
+   BestPractices
 
 

Documentation/ApiOverview/ContentElements/Introduction.rst

@@ -0,0 +1,90 @@
+.. include:: ../../Includes.txt
+
+
+.. _cePluginsIntroduction:
+
+============
+Introduction
+============
+
+What are content elements?
+==========================
+
+**Content elements** (often abbreviated as CE) are the building blocks
+that make up a page in TYPO3.
+
+Content elements are stored in the database table ``tt_content``. Each content
+element has a specific content element type, specified by the database field
+``tt_content.CType``. A content element can be of a type
+supplied by TYPO3, such as 'textmedia' (text with or without images or videos).
+Or it can have a custom type supplied
+by an extension such as 'carousel' provided by the bootstrap_package extension.
+
+Content elements are one of the elements (along with pages) that can be filled
+with content by editors and will be rendered in the frontend when a page is
+generated.
+
+Content elements are arranged on a page, depending on their
+
+* language (field: ``tt_content.sys_language_uid``)
+* sorting (field: ``tt_content.sorting``)
+* column (field: ``tt_content.colPos``)
+* etc.
+
+
+What are plugins?
+=================
+
+**Plugins** are a specific type of content elements. Typical characteristics of
+plugins are:
+
+* Used if more complex functionality is required
+* Plugins can be created using the Extbase framework or as pibase (AbstractPlugin)
+  plugin.
+* ``tt_content.CType`` = ``list`` and ``tt_content.list_type`` contains the
+  :ref:`plugin signature <naming-conventions-plugin-signature>`.
+
+A typical extension with plugins is the 'news' extension which comes with plugins
+to display news records in lists or as a single view. The news records are stored
+in a custom database table and can be edited in the backend (in the list module).
+
+Editing
+=======
+
+How to work with content elements and plugins?
+
+The "Getting Started Tutorial" describes how to work with :ref:`page content <t3start:page-content>`
+The "Tutorial for Editors" describes the :ref:`basic TYPO3 content elements <t3editors:content-types>`
+and how to work with them. Additional descriptions can be found the
+:ref:`fluid_styled_content <fsc:content-elements>` documentation.
+
+.. _cePluginsCustomize:
+
+Customizing
+===========
+
+:ref:`Backend Layouts <be-layout>` can be configured to define how content elements
+are arranged in the TYPO3 backend (in rows, columns, grids). This can be used in
+the frontend to determine how the content elements are to be arranged (e.g. in
+the footer of the page, left column etc.).
+
+Often content elements and plugins contain a number of fields. Not all of these may
+be relevant for your site. It is good practice to configure which fields will be
+displayed in the backend. There are a number of ways to do this:
+
+* :ref:`Backend user and group permissions <access-options>` can be used to restrict access to
+  content elements, to content on specific pages etc.
+* Fields can be hidden in the backend by using :ref:`TSconfig TCEFORM <t3tsconfig:tceform>`.
+* Page TSconfig can be used to :ref:`configure <content-element-wizard>` what is displayed in the "Content Element
+  Wizard".
+
+Creating new content elements
+=============================
+
+The following chapters handle how to create your own content element types and plugins.
+Specifically, check out:
+
+* :ref:`adding-your-own-content-elements`
+* :ref:`t3extbasebook:configuring-the-plugin` in the "Extbase / Fluid book"
+* How to make your plugins or content elements configurable by editors with
+  :ref:`flexforms`

Documentation/ApiOverview/FlexForms/Index.rst

@@ -22,11 +22,10 @@ to use input fields, select lists, show options conditionally and more.
 Example Use Cases
 =================
 
-* Use the plugin to configure a different view, e.g. list, single
-* The `bootstrap_package <https://extensions.typo3.org/extension/example/>`__
-  uses FlexForms to configure rendering options,
-  e.g. a transition interval and transition type (slide, fade)
-  for the carousel.
+The `bootstrap_package <https://extensions.typo3.org/extension/bootstrap_package/>`__
+uses FlexForms to configure rendering options,
+e.g. a transition interval and transition type (slide, fade)
+for the carousel.
 
 .. image:: Images/FlexFormCarousel.png
    :class: with-shadow

Documentation/DataFormats/Index.rst

@@ -1,12 +1,16 @@
+:orphan:
+
 .. include:: ../Includes.txt
 
 
 ============
 Data Formats
 ============
 
-.. toctree::
+This content has moved to:
+
+.. rst-class:: horizbuttons-tip-xxl
 
-   T3datastructure/Index
 
+- :ref:`t3ds`
 

Documentation/DataFormats/T3datastructure/Index.rst

@@ -3,9 +3,9 @@
 
 .. _t3ds:
 
-=================
-<T3DataStructure>
-=================
+===============
+T3DataStructure
+===============
 
 TYPO3 offers an XML format, T3DataStructure, which defines a
 hierarchical data structure. In itself the data structure definition
@@ -33,18 +33,21 @@ Some other facts about Data Structures (DS):
   "<T3DataStructure>"
 
 - The XML format generally complies with what can be converted into a
-  PHP array by :code:`\TYPO3\CMS\Core\Utility\GeneralUtility::xml2array()` - thus it directly reflects how a
+  PHP array by :php:`GeneralUtility::xml2array()` - thus it directly reflects how a
   multidimensional PHP array is constructed.
 
 - A Data Structure can be arranged in a set of "sheets". The purpose of
   sheets will depend on the application. Basically sheets are like a
   one-dimensional internal categorization of Data Structures.
 
 - Parsing a Data Structure into a PHP array is incredibly easy - just
-  pass it to :code:`\TYPO3\CMS\Core\Utility\GeneralUtility::xml2array()` (see the :ref:`t3ds-parsing` section).
+  pass it to :php:`GeneralUtility::xml2array()` (see the :ref:`t3ds-parsing` section).
 
 - "DS" is sometimes used as short for Data Structure
 
+
+**Next chapters**
+
 .. toctree::
    :titlesonly: