[TASK] Suggest TCA overrides for FSC content elements
[Packages/TYPO3.CMS.git] / typo3 / sysext / fluid_styled_content / Documentation / AddingYourOwnContentElements / Index.rst
1 .. include:: ../Includes.txt
2
3
4 .. _adding-your-own-content-elements:
5
6 ================================
7 Adding your own content elements
8 ================================
9
10 .. note::
11
12    This part is written for developers!
13
14 A content element can be based on already available fields in the `tt_content` table,
15 or it might be that you need extra fields. This is done the same way as you do for
16 your own extensions, extending TCA. Depending on the data in the `tt_content` table,
17 you can send the data immediately to the Fluid template or use a data processor in
18 front to do some data manipulation. The content elements in the extension "fluid_styled_content"
19 are using both as well. A data processor is sometimes used to convert a string (like
20 the `bodytext` field in content element "table") to an array, so Fluid does not
21 have to deal with this manipulation or transformation.
22
23
24 .. _AddingCE-use-an-extension:
25
26 Use an extension
27 ================
28
29 Advisable is to make your own extension. In our example we've used the extension key
30 `your_extension_key`. If you have plans to publish your extension, do not forget to
31 lookup for the availability of your desired key and register it at the
32 `"extension keys" page <http://typo3.org/extensions/extension-keys/>`_. login in
33 `typo3.org <http://typo3.org//>`_ is required.
34
35 Since this part is written for developers, we will not explain in full detail how an
36 extension works.
37
38 .. _AddingCE-PageTSconfig:
39
40 PageTSconfig
41 ------------
42 First we need to add our new content element to the "New Content Element Wizard" and
43 define its CType. We call it "yourextensionkey_newcontentelement".
44
45 .. code-block:: typoscript
46
47    mod.wizards.newContentElement.wizardItems.common {
48       elements {
49          yourextensionkey_newcontentelement {
50             iconIdentifier = your-icon-identifier
51             title = LLL:EXT:your_extension_key/Resources/Private/Language/Tca.xlf:yourextensionkey_newcontentelement.wizard.title
52             description = LLL:EXT:your_extension_key/Resources/Private/Language/Tca.xlf:yourextensionkey_newcontentelement.wizard.description
53             tt_content_defValues {
54                CType = yourextensionkey_newcontentelement
55             }
56          }
57       }
58       show := addToList(yourextensionkey_newcontentelement)
59    }
60
61
62 .. _AddingCE-TCA-Overrides-tt_content:
63
64 Configuration/TCA/Overrides/tt_content.php
65 ------------------------------------------
66
67 Then we need to add the content element to the "Type" dropdown, where you can select
68 the type of content element:
69
70 .. code-block:: php
71
72    // Adds the content element to the "Type" dropdown
73    \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addPlugin(
74       array(
75          'LLL:EXT:your_extension_key/Resources/Private/Language/Tca.xlf:yourextensionkey_newcontentelement',
76          'yourextensionkey_newcontentelement',
77          'EXT:your_extension_key/Resources/Public/Icons/ContentElements/yourextensionkey_newcontentelement.gif'
78       ),
79       'CType',
80       'your_extension_key'
81    );
82
83 Then we configure the backend fields for our new content element:
84
85 .. code-block:: php
86
87    // Configure the default backend fields for the content element
88    $GLOBALS['TCA']['tt_content']['types']['yourextensionkey_newcontentelement'] = array(
89       'showitem' => '
90             --palette--;LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xml:palette.general;general,
91             --palette--;LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xml:palette.header;header,
92          --div--;LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xml:tabs.appearance,
93             --palette--;LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xml:palette.frames;frames,
94          --div--;LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xml:tabs.access,
95             --palette--;LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xml:palette.visibility;visibility,
96             --palette--;LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xml:palette.access;access,
97          --div--;LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xml:tabs.extended
98    ');
99
100 .. _AddingCE-TCA-Overrides-sys_template:
101
102 Configuration/TCA/Overrides/sys_template.php
103 --------------------------------------------
104
105 Since we need to use TypoScript as well, we add an entry in the static template list
106 found in sys_templates for static TS:
107
108 .. code-block:: php
109
110    // Add an entry in the static template list found in sys_templates for static TS
111    \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile(
112       'your_extension_key',
113       'Configuration/TypoScript',
114       'Your description'
115    );
116
117
118 .. _AddingCE-setup-txt:
119
120 setup.txt
121 ---------
122
123 As defined in `Configuration/TCA/Overrides/tt_content.php`, this file is in the directory
124 `Configuration/TypoScript` of our own extension. You can have two options in the TypoScript:
125
126 - Send all the data from the tt\_content table for this particular content element
127   directly to a Fluid template
128
129   .. code-block:: typoscript
130
131      tt_content {
132         yourextensionkey_newcontentelement < lib.fluidContent
133         yourextensionkey_newcontentelement {
134            templateName = NewContentElement.html
135         }
136      }
137
138 - Or use data processors in front of the view to do some data manipulation or other stuff
139   you would like to do before sending everything to the view. First tell the FLUIDTEMPLATE
140   content object what the name of the template is by using the parameter `templateName`,
141   then add the full class name for the data processor. You can send your own parameters
142   to the processor as well:
143
144 .. code-block:: typoscript
145
146    tt_content {
147       yourextensionkey_newcontentelement < lib.fluidContent
148       yourextensionkey_newcontentelement {
149          templateName = NewContentElement.html
150          dataProcessing {
151             1 = Vendor\YourExtensionKey\DataProcessing\NewContentElementProcessor
152             1 {
153                useHere = theConfigurationOfTheDataProcessor
154             }
155          }
156       }
157    }
158
159 You need to add the templateRootPath to your own extension as well, and if you are using
160 it, partialRootPaths and layoutRootPaths:
161
162 .. code-block:: typoscript
163
164    lib.fluidContent {
165       templateRootPaths {
166          200 = EXT:your_extension_key/Resources/Private/Templates/
167       }
168    }
169
170
171 .. _AddingCE-Data-Processor:
172
173 Data Processor
174 --------------
175
176 In our :ref:`AddingCE-setup-txt` example above, we put the data processor in the directory
177 :file:`Classes/DataProcessing`. The file :file:`NewContentElementProcessor.php` could
178 look like:
179
180 .. code-block:: php
181
182    <?php
183    namespace Vendor\YourExtensionKey\DataProcessing;
184
185    /*
186     * This file is part of the TYPO3 CMS project.
187     *
188     * It is free software; you can redistribute it and/or modify it under
189     * the terms of the GNU General Public License, either version 2
190     * of the License, or any later version.
191     *
192     * For the full copyright and license information, please read the
193     * LICENSE.txt file that was distributed with this source code.
194     *
195     * The TYPO3 project - inspiring people to share!
196     */
197
198    use TYPO3\CMS\Frontend\ContentObject\ContentObjectRenderer;
199    use TYPO3\CMS\Frontend\ContentObject\DataProcessorInterface;
200
201    /**
202     * Class for data processing for the content element "My new content element"
203     */
204    class NewContentElementProcessor implements DataProcessorInterface
205    {
206
207       /**
208        * Process data for the content element "My new content element"
209        *
210        * @param ContentObjectRenderer $cObj The data of the content element or page
211        * @param array $contentObjectConfiguration The configuration of Content Object
212        * @param array $processorConfiguration The configuration of this processor
213        * @param array $processedData Key/value store of processed data (e.g. to be passed to a Fluid View)
214        * @return array the processed data as key/value store
215        */
216       public function process(
217          ContentObjectRenderer $cObj,
218          array $contentObjectConfiguration,
219          array $processorConfiguration,
220          array $processedData
221       )
222       {
223          $processedData['foo'] = 'This variable will be passed to Fluid';
224
225          return $processedData;
226       }
227    }
228
229
230 .. _AddingCE-ext-localconf-php:
231
232 ext\_localconf.php
233 ------------------
234
235 If you want to generate a special preview in the backend "Web > Page" module, you can use
236 a hook for this:
237
238 .. code-block:: php
239
240    // Register for hook to show preview of tt_content element of CType="yourextensionkey_newcontentelement" in page module
241    $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['cms/layout/class.tx_cms_layout.php']['tt_content_drawItem']['yourextensionkey_newcontentelement'] =
242       \Vendor\YourExtensionKey\Hooks\PageLayoutView\NewContentElementPreviewRenderer::class;
243
244
245 .. _AddingCE-Content-Element-Preview-Renderer:
246
247 Content Element Preview Renderer
248 --------------------------------
249
250 The preview renderer :file:`NewContentElementPreviewRenderer.php`, for the backend, has
251 been put in the directory :file:`Classes/Hooks/PageLayoutView` and could look like this:
252
253 .. code-block:: php
254
255    <?php
256    namespace Vendor\YourExtensionKey\Hooks\PageLayoutView;
257
258    /*
259     * This file is part of the TYPO3 CMS project.
260     *
261     * It is free software; you can redistribute it and/or modify it under
262     * the terms of the GNU General Public License, either version 2
263     * of the License, or any later version.
264     *
265     * For the full copyright and license information, please read the
266     * LICENSE.txt file that was distributed with this source code.
267     *
268     * The TYPO3 project - inspiring people to share!
269     */
270
271    use \TYPO3\CMS\Backend\View\PageLayoutViewDrawItemHookInterface;
272    use \TYPO3\CMS\Backend\View\PageLayoutView;
273
274    /**
275     * Contains a preview rendering for the page module of CType="yourextensionkey_newcontentelement"
276     */
277    class NewContentElementPreviewRenderer implements PageLayoutViewDrawItemHookInterface
278    {
279
280       /**
281        * Preprocesses the preview rendering of a content element of type "My new content element"
282        *
283        * @param \TYPO3\CMS\Backend\View\PageLayoutView $parentObject Calling parent object
284        * @param bool $drawItem Whether to draw the item using the default functionality
285        * @param string $headerContent Header content
286        * @param string $itemContent Item content
287        * @param array $row Record row of tt_content
288        *
289        * @return void
290        */
291       public function preProcess(
292          PageLayoutView &$parentObject,
293          &$drawItem,
294          &$headerContent,
295          &$itemContent,
296          array &$row
297       )
298       {
299          if ($row['CType'] === 'yourextensionkey_newcontentelement') {
300             $itemContent .= '<p>We can change our preview here!</p>';
301
302             $drawItem = false;
303          }
304       }
305    }
306
307
308 .. _AddingCE-fluid-templates:
309
310 Fluid templates
311 ---------------
312
313 For the final rendering you need a Fluid template. This template will be located at the
314 directory and file name which you have entered in :ref:`AddingCE-setup-txt` using the parameter
315 `templateName`.
316
317 Just to show the variable foo, like we defined at :ref:`AddingCE-data-processor`,
318 we can use the following markup:
319
320 .. code-block:: html
321
322    <h1>{foo}</h1>
323