diff --git a/Documentation/ContentBlocks/Index.rst b/Documentation/ContentBlocks/Index.rst new file mode 100644 index 0000000..d41af81 --- /dev/null +++ b/Documentation/ContentBlocks/Index.rst @@ -0,0 +1,158 @@ +:navigation-title: Custom Content Blocks +.. include:: /Includes.rst.txt + +.. _content-blocks: + +===================== +Custom Content Blocks +===================== + +When we filled the `stage with content `_ +we noticed that the content does not look like the content within the original +HTMl layout. + +This is because the stage does not contain normal content, as provided by +Fluid-Styled Content, but a Jumbotron element or a slider. + +.. note:: + The extension :composer:`friendsoftypo3/content-blocks` is not an official + part of the TYPO3 Core yet. It is also possible to + `Create a custom content element with TYPO3 Core only `_. + +.. _content-blocks-installation: + +Install extension Content Blocks +================================ + +The extension :composer:`friendsoftypo3/content-blocks` is an extension that +is not part of the TYPO3 Core but maintained by a group of community members. + +There are plans to integrate this extension into the Core, however at the +time of writing there are no finite decisions yet. + +First install the extension :composer:`friendsoftypo3/content-blocks`: + +.. code-block:: bash + + ddev composer req friendsoftypo3/content-blocks + +Set up the extension and delete all caches: + +.. code-block:: bash + + ddev typo3 extension:setup + ddev typo3 cache:flush + +.. _content-blocks-jumbotron: + +The jumbotron Content Block +=========================== + +The site package you generated in step +`Generate a site package `_ +comes with two content elements. We look at the more basic content elements first. + +You can now replace the content element in the area "Stage" of start page with +one of type "Jumbotron". + +.. figure:: /Images/ContentBlocks/CreateContentElement.png + :alt: Screenshot of the "New Page Content" dialog with the Carousel and Jumbotron as additional features + + The new Content Blocks "Jumbotron" and "Carousel" + +You can now create a jumbotron with a button and a link. + +Directory :path:`packages/my_site_package/ContentBlocks/ContentElements` contains +one directory for each Content Block that can be used as normal Content Elements. + +.. _content-blocks-jumbotron-directory: + +Directory structure of a Content Block +-------------------------------------- + +A Content Block consists of a configuration (:file:`config.yaml`), a template and +optionally assets and or language files: + +The jumbotron consists of the following files: + +.. directory-tree:: + :level: 2 + :show-file-icons: true + + * packages/my_site_package/ContentBlocks/ContentElements/jumbotron + + * assets + + * icon.svg + + * language + + * labels.xlf + + * templates + + * frontend.html + + * config.yaml + +.. _content-blocks-jumbotron-config: + +The configuration of the jumbotron Content Block +------------------------------------------------ + +File :path:`packages/my_site_package/ContentBlocks/ContentElements/jumbotron/config.yaml` +defines what fields should be available for the Content Block in the backend: + +.. literalinclude:: /CodeSnippets/my_site_package/ContentBlocks/ContentElements/jumbotron/config.yaml + :caption: packages/my_site_package/ContentBlocks/ContentElements/jumbotron/config.yaml + :linenos: + +Each Content Block must have a unique name with a prefix of your choice that +should be unique within your project. (Line 1) + +It is possible to use fields that are already pre-defined in the TYPO3 Core like +`header` (Line 8) and `bodytext` (Line 11). + +We also newly define two fields, one of type `Text `_ +(Line 15-19) and one of type `Link `_ +(Line 21-23). You can find all available types here: `Field Types `_. + +The meaning behind the other settings here can be found in the +`YAML reference of the Content Blocks guide `_. + +.. _content-blocks-jumbotron-template: + +The jumbotron template +---------------------- + +The frontend template for the Content Block "Jumbotron" is a normal Fluid +template. You already used Fluid for the +`Page templates `_ +and to adjust the templates of Fluid-Styled Content elements in chapter +`Overriding the default templates of content elements `_. + +.. literalinclude:: /CodeSnippets/my_site_package/ContentBlocks/ContentElements/jumbotron/templates/frontend.html + :caption: packages/my_site_package/ContentBlocks/ContentElements/jumbotron/templates/frontend.html + :linenos: + +Line 3: The values of the database entry of the current content element can be +found in variable `{data}`. In this line we render the content of the field +`header`. The field was defined in line 8 of the :file:`config.yaml`. + +Line 4: Here we output the content of field `bodytext` as this field is a +Rich-Text Editor we use the +`Format.html ViewHelper `_ +to format and sanitize the output. + +Line 5: We use the `Link.typolink ViewHelper `_ +to render a link to the target that was defined in our custom field `button_link`. + +.. _content-blocks-next: + +Next steps +========== + +* The generated site package contains a second, more elaborate example in + directory :path:`packages/my_site_package/ContentBlocks/ContentElements/carousel`. +* Learn how to use the `Kickstart command `_ + to create your own Content Blocks. diff --git a/Documentation/Images/ContentBlocks/CreateContentElement.png b/Documentation/Images/ContentBlocks/CreateContentElement.png new file mode 100644 index 0000000..2ef2967 Binary files /dev/null and b/Documentation/Images/ContentBlocks/CreateContentElement.png differ diff --git a/Documentation/Index.rst b/Documentation/Index.rst index d293295..bb91374 100644 --- a/Documentation/Index.rst +++ b/Documentation/Index.rst @@ -100,6 +100,14 @@ https://github.com/TYPO3-Documentation/site_package .. card-footer:: :ref:`Learn about the configuration of a site package ` :button-style: btn btn-secondary stretched-link + .. card:: :ref:`Content Blocks ` + + We explain how the TYPO3 Extension :composer:`friendsoftypo3/content-blocks` + can be used to create custom Content Elements, for example for a jumbotron + or slider. + + .. card-footer:: :ref:`Learn to create custom Content Elements ` + :button-style: btn btn-secondary stretched-link .. card:: :ref:`Extension Configuration ` @@ -131,6 +139,7 @@ https://github.com/TYPO3-Documentation/site_package MainMenuCreation/Index SiteSets/Index ContentElementRendering/Index + ContentBlocks/Index Faq/Index NextSteps/Index