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