4ca8fb68922c47334ab1dba9ad89312d156120ba
[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          --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:general,
91             --palette--;;general,
92             --palette--;;headers,
93             bodytext;LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xlf:bodytext_formlabel,
94          --div--;LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xlf:tabs.appearance,
95             --palette--;;frames,
96             --palette--;;appearanceLinks,
97          --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:language,
98             --palette--;;language,
99          --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:access,
100             --palette--;;hidden,
101             --palette--;;access,
102          --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:categories,
103             categories,
104          --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:notes,
105             rowDescription,
106          --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:extended,
107       ',
108       'columnsOverrides' => [
109          'bodytext' => [
110             'config' => [
111                'enableRichtext' => true,
112                'richtextConfiguration' => 'default'
113             ]
114          ]
115       ]
116    );
117
118 .. _AddingCE-TCA-Overrides-sys_template:
119
120 Configuration/TCA/Overrides/sys_template.php
121 --------------------------------------------
122
123 Since we need to use TypoScript as well, we add an entry in the static template list
124 found in sys_templates for static TS:
125
126 .. code-block:: php
127
128    // Add an entry in the static template list found in sys_templates for static TS
129    \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile(
130       'your_extension_key',
131       'Configuration/TypoScript',
132       'Your description'
133    );
134
135
136 .. _AddingCE-setup-txt:
137
138 setup.txt
139 ---------
140
141 As defined in `Configuration/TCA/Overrides/tt_content.php`, this file is in the directory
142 `Configuration/TypoScript` of our own extension. You can have two options in the TypoScript:
143
144 - Send all the data from the tt\_content table for this particular content element
145   directly to a Fluid template
146
147   .. code-block:: typoscript
148
149      tt_content {
150         yourextensionkey_newcontentelement =< lib.contentElement
151         yourextensionkey_newcontentelement {
152            templateName = NewContentElement
153         }
154      }
155
156 - Or use data processors in front of the view to do some data manipulation or other stuff
157   you would like to do before sending everything to the view. First tell the FLUIDTEMPLATE
158   content object what the name of the template is by using the parameter `templateName`,
159   then add the full class name for the data processor. You can send your own parameters
160   to the processor as well:
161
162 .. code-block:: typoscript
163
164    tt_content {
165       yourextensionkey_newcontentelement =< lib.contentElement
166       yourextensionkey_newcontentelement {
167          templateName = NewContentElement
168          dataProcessing {
169             1 = Vendor\YourExtensionKey\DataProcessing\NewContentElementProcessor
170             1 {
171                useHere = theConfigurationOfTheDataProcessor
172             }
173          }
174       }
175    }
176
177 You need to add the templateRootPath to your own extension as well, and if you are using
178 it, partialRootPaths and layoutRootPaths:
179
180 .. code-block:: typoscript
181
182    lib.contentElement {
183       templateRootPaths {
184          200 = EXT:your_extension_key/Resources/Private/Templates/
185       }
186    }
187
188
189 .. _AddingCE-Data-Processor:
190
191 Data Processor
192 --------------
193
194 In our :ref:`AddingCE-setup-txt` example above, we put the data processor in the directory
195 :file:`Classes/DataProcessing`. The file :file:`NewContentElementProcessor.php` could
196 look like:
197
198 .. code-block:: php
199
200    <?php
201    namespace Vendor\YourExtensionKey\DataProcessing;
202
203    /*
204     * This file is part of the TYPO3 CMS project.
205     *
206     * It is free software; you can redistribute it and/or modify it under
207     * the terms of the GNU General Public License, either version 2
208     * of the License, or any later version.
209     *
210     * For the full copyright and license information, please read the
211     * LICENSE.txt file that was distributed with this source code.
212     *
213     * The TYPO3 project - inspiring people to share!
214     */
215
216    use TYPO3\CMS\Frontend\ContentObject\ContentObjectRenderer;
217    use TYPO3\CMS\Frontend\ContentObject\DataProcessorInterface;
218
219    /**
220     * Class for data processing for the content element "My new content element"
221     */
222    class NewContentElementProcessor implements DataProcessorInterface
223    {
224
225       /**
226        * Process data for the content element "My new content element"
227        *
228        * @param ContentObjectRenderer $cObj The data of the content element or page
229        * @param array $contentObjectConfiguration The configuration of Content Object
230        * @param array $processorConfiguration The configuration of this processor
231        * @param array $processedData Key/value store of processed data (e.g. to be passed to a Fluid View)
232        * @return array the processed data as key/value store
233        */
234       public function process(
235          ContentObjectRenderer $cObj,
236          array $contentObjectConfiguration,
237          array $processorConfiguration,
238          array $processedData
239       )
240       {
241          $processedData['foo'] = 'This variable will be passed to Fluid';
242
243          return $processedData;
244       }
245    }
246
247
248 .. _AddingCE-ext-localconf-php:
249
250 ext\_localconf.php
251 ------------------
252
253 If you want to generate a special preview in the backend "Web > Page" module, you can use
254 a hook for this:
255
256 .. code-block:: php
257
258    // Register for hook to show preview of tt_content element of CType="yourextensionkey_newcontentelement" in page module
259    $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['cms/layout/class.tx_cms_layout.php']['tt_content_drawItem']['yourextensionkey_newcontentelement'] =
260       \Vendor\YourExtensionKey\Hooks\PageLayoutView\NewContentElementPreviewRenderer::class;
261
262
263 .. _AddingCE-Content-Element-Preview-Renderer:
264
265 Content Element Preview Renderer
266 --------------------------------
267
268 The preview renderer :file:`NewContentElementPreviewRenderer.php`, for the backend, has
269 been put in the directory :file:`Classes/Hooks/PageLayoutView` and could look like this:
270
271 .. code-block:: php
272
273    <?php
274    namespace Vendor\YourExtensionKey\Hooks\PageLayoutView;
275
276    /*
277     * This file is part of the TYPO3 CMS project.
278     *
279     * It is free software; you can redistribute it and/or modify it under
280     * the terms of the GNU General Public License, either version 2
281     * of the License, or any later version.
282     *
283     * For the full copyright and license information, please read the
284     * LICENSE.txt file that was distributed with this source code.
285     *
286     * The TYPO3 project - inspiring people to share!
287     */
288
289    use \TYPO3\CMS\Backend\View\PageLayoutViewDrawItemHookInterface;
290    use \TYPO3\CMS\Backend\View\PageLayoutView;
291
292    /**
293     * Contains a preview rendering for the page module of CType="yourextensionkey_newcontentelement"
294     */
295    class NewContentElementPreviewRenderer implements PageLayoutViewDrawItemHookInterface
296    {
297
298       /**
299        * Preprocesses the preview rendering of a content element of type "My new content element"
300        *
301        * @param \TYPO3\CMS\Backend\View\PageLayoutView $parentObject Calling parent object
302        * @param bool $drawItem Whether to draw the item using the default functionality
303        * @param string $headerContent Header content
304        * @param string $itemContent Item content
305        * @param array $row Record row of tt_content
306        *
307        * @return void
308        */
309       public function preProcess(
310          PageLayoutView &$parentObject,
311          &$drawItem,
312          &$headerContent,
313          &$itemContent,
314          array &$row
315       )
316       {
317          if ($row['CType'] === 'yourextensionkey_newcontentelement') {
318             $itemContent .= '<p>We can change our preview here!</p>';
319
320             $drawItem = false;
321          }
322       }
323    }
324
325
326 .. _AddingCE-fluid-templates:
327
328 Fluid templates
329 ---------------
330
331 For the final rendering you need a Fluid template. This template will be located at the
332 directory and file name which you have entered in :ref:`AddingCE-setup-txt` using the parameter
333 `templateName`.
334
335 Just to show the variable foo, like we defined at :ref:`AddingCE-data-processor`,
336 we can use the following markup:
337
338 .. code-block:: html
339
340    <h1>{foo}</h1>
341