Skip to content

Commit

Permalink
[DOCS] Remove "Adding Your Own Content Elements"
Browse files Browse the repository at this point in the history 
Content has been migrated to "TYPO3 Explained"

Reduce the content to a stub and add link.

Resolves: #89949
Releases: master, 9.5, 8.7
Change-Id: I4c69c8a1f74bea223110b9b6a07e035a03183d87
Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/62641
Tested-by: TYPO3com <noreply@typo3.com>
Tested-by: Björn Jacob <bjoern.jacob@tritum.de>
Tested-by: Daniel Goerz <daniel.goerz@posteo.de>
Reviewed-by: Björn Jacob <bjoern.jacob@tritum.de>
Reviewed-by: Daniel Goerz <daniel.goerz@posteo.de>
  • Loading branch information
@sypets @ervaude
sypets authored and ervaude committed Dec 15, 2019
1 parent 2ce9075 commit 4f2f7f5
Showing 1 changed file with 6 additions and 342 deletions.
348 changes: 6 additions & 342 deletions ...ysext/fluid_styled_content/Documentation/AddingYourOwnContentElements/Index.rst
View file
Expand Up @@ -3,350 +3,14 @@
.. _adding-your-own-content-elements:

================================
Adding your own content elements
Adding Your Own Content Elements
================================

.. note::
.. attention::

This part is written for developers!
This page has been merged into :ref:`TYPO3 Explained <t3coreapi:adding-your-own-content-elements>`
since core version 8.7.

A content element can be based on already available fields in the `tt_content` table and/or extra fields you can add to the `tt_content` table.
This is done the same way as you do for your own extensions by :ref:`extending TCA <t3coreapi:extending>`.
Depending on the data in the `tt_content` table, you can send the data immediately to the :ref:`cobj-fluidtemplate`
or use a :ref:`data processor <t3tsref:cobj-fluidtemplate-properties-dataprocessing>` in front to do some data manipulation.
The content elements in the extension "fluid_styled_content" are using both as well.
A data processor is sometimes used to convert a string (like the `bodytext` field in content element "table")
to an array or fetch a related record (e.g. a FAL file), so Fluid does not have to deal with this manipulation or transformation.


.. _AddingCE-use-an-extension:

Use an extension
================

We recommend to create your own extension for adding content elements.
The following example uses the extension key `your_extension_key`.
If you have plans to publish your extension, do not forget to check
for the availability of your desired key
and register it at the `"extension keys" page <https://extensions.typo3.org/my-extensions/>`_
(prior login at `typo3.org <https://typo3.org/>`_ is required).

Since this part is written for developers, it will not explain in full detail how an extension works.

.. _AddingCE-PageTSconfig:
.. _RegisterCE:
.. _AddingCE-TCA-Overrides-tt_content:

1. Register the content element
===============================

First add your new content element to the "New Content Element Wizard" and define its `CType` in PageTSconfig.
The example content element is called `yourextensionkey_newcontentelement`:

.. code-block:: typoscript
mod.wizards.newContentElement.wizardItems.common {
elements {
yourextensionkey_newcontentelement {
iconIdentifier = your-icon-identifier
title = LLL:EXT:your_extension_key/Resources/Private/Language/Tca.xlf:yourextensionkey_newcontentelement.wizard.title
description = LLL:EXT:your_extension_key/Resources/Private/Language/Tca.xlf:yourextensionkey_newcontentelement.wizard.description
tt_content_defValues {
CType = yourextensionkey_newcontentelement
}
}
}
show := addToList(yourextensionkey_newcontentelement)
}
You need to :ref:`register the icon identifier <t3coreapi:icon-registration>` with the icon API in your :file:`ext_localconf.php`.

Then you need to add the content element to the "Type" dropdown, where you can select
the type of content element in the file :file:`Configuration/TCA/Overrides/tt_content.php`:

.. code-block:: php
// Adds the content element to the "Type" dropdown
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addPlugin(
[
'LLL:EXT:your_extension_key/Resources/Private/Language/Tca.xlf:yourextensionkey_newcontentelement',
'yourextensionkey_newcontentelement',
'EXT:your_extension_key/Resources/Public/Icons/ContentElements/yourextensionkey_newcontentelement.gif',
],
'CType',
'your_extension_key'
);
.. _ConfigureCE-Fields:

2. Configure fields
===================

Then you need to configure the backend fields for your new content element in the file
:file:`Configuration/TCA/Overrides/tt_content.php`:

.. code-block:: php
// Configure the default backend fields for the content element
$GLOBALS['TCA']['tt_content']['types']['yourextensionkey_newcontentelement'] = [
'showitem' => '
--div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:general,
--palette--;;general,
--palette--;;headers,
bodytext;LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xlf:bodytext_formlabel,
--div--;LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xlf:tabs.appearance,
--palette--;;frames,
--palette--;;appearanceLinks,
--div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:language,
--palette--;;language,
--div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:access,
--palette--;;hidden,
--palette--;;access,
--div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:categories,
categories,
--div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:notes,
rowDescription,
--div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:extended,
',
'columnsOverrides' => [
'bodytext' => [
'config' => [
'enableRichtext' => true,
'richtextConfiguration' => 'default',
],
],
],
];
.. _ConfigureCE-Frontend:

3. Configure the frontend template
==================================

Since TypoScript configuration is needed as well,add an entry in the static template list
found in `sys_templates` for static TypoScript in :file:`Configuration/TCA/Overrides/sys_template.php`:

.. code-block:: php
// Add an entry in the static template list found in sys_templates for static TS
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile(
'your_extension_key',
'Configuration/TypoScript',
'Your description'
);
As defined in :file:`Configuration/TCA/Overrides/sys_template.php`, the file :file:`setup.typoscript` is in the directory
:file:`Configuration/TypoScript/` of your own extension.

To ensure your custom content element templates can be found you need to extend the global
:typoscript:`templateRootPaths` with a path within your extension:

.. code-block:: typoscript
lib.contentElement {
templateRootPaths {
200 = EXT:your_extension_key/Resources/Private/Templates/
}
}
You can use an arbitrary index (`200` here), just make sure it is unique. If you use partials
and layouts, you need to do the same for :ref:`t3tsref:cobj-fluidtemplate-properties-partialrootpaths`
and :ref:`t3tsref:cobj-fluidtemplate-properties-layoutrootpaths`.

Now you can register the rendering of your custom content element using a Fluid template:

.. code-block:: typoscript
tt_content {
yourextensionkey_newcontentelement =< lib.contentElement
yourextensionkey_newcontentelement {
templateName = NewContentElement
}
}
In this example a :ref:`cobj-fluidtemplate` content object is created using a reference from :typoscript:`lib.contentElement`
with a template identified by the :ref:`t3tsref:cobj-fluidtemplate-properties-templatename` `NewContentElement`.
This will load a :file:`NewContentElement.html` template file from the :typoscript:`templateRootPaths`.

.. note::

The :typoscript:`lib.contentElement` path is defined in
:file:`EXT:fluid_styled_content/Configuration/TypoScript/Helper/ContentElement.typoscript`.


For the final rendering you need a Fluid template. This template will be located at the
directory and file name which you have entered in :file:`setup.typoscript` using the parameter
:typoscript:`templateName`. Now we can use the `tt_content` fields in the Fluid template by accessing them
via the `data` variable. The following example shows the text entered in the richtext enabled
field `bodytext` formatted using the defined richtext configuration:

.. code-block:: html

<div>{data.bodytext -> f:format.html()}</div>


.. _ConfigureCE-Preview:

4. Optional: configure custom backend preview
=============================================

If you want to generate a special preview in the backend "Web > Page" module, you can use
a hook for this:

.. code-block:: php
// Register for hook to show preview of tt_content element of CType="yourextensionkey_newcontentelement" in page module
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['cms/layout/class.tx_cms_layout.php']['tt_content_drawItem']['yourextensionkey_newcontentelement'] =
\Vendor\YourExtensionKey\Hooks\PageLayoutView\NewContentElementPreviewRenderer::class;
The preview renderer :file:`NewContentElementPreviewRenderer.php`, for the backend, has
been put in the directory :file:`Classes/Hooks/PageLayoutView/` and could look like this:

.. code-block:: php
<?php
namespace Vendor\YourExtensionKey\Hooks\PageLayoutView;
/*
* This file is part of the TYPO3 CMS project.
*
* It is free software; you can redistribute it and/or modify it under
* the terms of the GNU General Public License, either version 2
* of the License, or any later version.
*
* For the full copyright and license information, please read the
* LICENSE.txt file that was distributed with this source code.
*
* The TYPO3 project - inspiring people to share!
*/
use \TYPO3\CMS\Backend\View\PageLayoutViewDrawItemHookInterface;
use \TYPO3\CMS\Backend\View\PageLayoutView;
/**
* Contains a preview rendering for the page module of CType="yourextensionkey_newcontentelement"
*/
class NewContentElementPreviewRenderer implements PageLayoutViewDrawItemHookInterface
{
/**
* Preprocesses the preview rendering of a content element of type "My new content element"
*
* @param \TYPO3\CMS\Backend\View\PageLayoutView $parentObject Calling parent object
* @param bool $drawItem Whether to draw the item using the default functionality
* @param string $headerContent Header content
* @param string $itemContent Item content
* @param array $row Record row of tt_content
*
* @return void
*/
public function preProcess(
PageLayoutView &$parentObject,
&$drawItem,
&$headerContent,
&$itemContent,
array &$row
) {
if ($row['CType'] === 'yourextensionkey_newcontentelement') {
$itemContent .= '<p>We can change our preview here!</p>';
$drawItem = false;
}
}
}
.. _ConfigureCE-Extend-tt_content:

5. Optional: extend tt_content
==============================

.. todo::

This will be filled in another patch.

.. _ConfigureCE-DataProcessors:

6. Optional: use data processors
================================

You can use data processors for some data manipulation or other actions you would like to perform before passing everything to the view.
This is done in the :ref:`dataProcessing <t3tsref:cobj-fluidtemplate-properties-dataprocessing>` section where you can add an arbitrary number of data processors,
each with a fully qualified class name (FQCN) and optional parameters to be used in the data processor:

.. code-block:: typoscript
tt_content {
yourextensionkey_newcontentelement =< lib.contentElement
yourextensionkey_newcontentelement {
templateName = NewContentElement
dataProcessing {
1 = Vendor\YourExtensionKey\DataProcessing\NewContentElementProcessor
1 {
exampleOptionName = exampleOptionValue
}
}
}
}
In the example :file:`setup.typoscript` above, the data processor is located in the directory
:file:`Classes/DataProcessing/`. The file :file:`NewContentElementProcessor.php` could
look like this:

.. code-block:: php
<?php
declare(strict_types = 1);
namespace Vendor\YourExtensionKey\DataProcessing;
/*
* This file is part of the TYPO3 CMS project.
*
* It is free software; you can redistribute it and/or modify it under
* the terms of the GNU General Public License, either version 2
* of the License, or any later version.
*
* For the full copyright and license information, please read the
* LICENSE.txt file that was distributed with this source code.
*
* The TYPO3 project - inspiring people to share!
*/
use TYPO3\CMS\Frontend\ContentObject\ContentObjectRenderer;
use TYPO3\CMS\Frontend\ContentObject\DataProcessorInterface;
/**
* Class for data processing for the content element "My new content element"
*/
class NewContentElementProcessor implements DataProcessorInterface
{
/**
* Process data for the content element "My new content element"
*
* @param ContentObjectRenderer $cObj The data of the content element or page
* @param array $contentObjectConfiguration The configuration of Content Object
* @param array $processorConfiguration The configuration of this processor
* @param array $processedData Key/value store of processed data (e.g. to be passed to a Fluid View)
* @return array the processed data as key/value store
*/
public function process(
ContentObjectRenderer $cObj,
array $contentObjectConfiguration,
array $processorConfiguration,
array $processedData
) {
$processedData['variableName'] = 'This variable will be passed to Fluid';
return $processedData;
}
}
Just to show the variable `variableName`,
like defined in :ref:`ConfigureCE-Data-Processor`,
you can use the following markup:

.. code-block:: html

<h1>{variableName}</h1>
**Older versions:**

Please refer to "Related Links" in the lower left corner of the page.

0 comments on commit 4f2f7f5

Please sign in to comment.