diff --git a/Documentation/Global/Page/Index.rst b/Documentation/Global/Page/Index.rst index 4e2dba2..efecac5 100644 --- a/Documentation/Global/Page/Index.rst +++ b/Documentation/Global/Page/Index.rst @@ -1,10 +1,29 @@ -.. This reStructured text file has been automatically generated, do not change. + .. include:: /Includes.rst.txt +.. _typo3-fluid-page-viewhelpers: + +================ +Page ViewHelpers +================ + +.. versionadded:: 14.0 + +The Page ViewHelpers provide access to page-level functionality in frontend +Fluid templates. They are used to control aspects of the rendered HTML +document that belong to the page itself rather than to individual content +elements. + +Typical use cases include: -==== -Page -==== +* setting the document title +* defining SEO and social media meta tags +* injecting additional markup into the HTML `` section +The Page ViewHelpers are designed to be used together and integrate with +TYPO3’s frontend rendering and MetaTagManager systems. + +For detailed information about each ViewHelper and its arguments, refer to +the individual reference pages: .. toctree:: :titlesonly: @@ -12,3 +31,45 @@ Page */Index * + +.. _typo3-fluid-page-viewhelpers-integrated-example: + +Setting meta data in a PAGEVIEW layout via Fluid +================================================ + +The following example shows how multiple Page ViewHelpers can be combined +in a `PAGEVIEW `_ +layout to manage common page-level concerns such as the document title, +SEO-related meta tags, OpenGraph and Twitter / X meta data, as well as +favicon and other `` assets. + +This approach is typically used in site packages and custom frontend +rendering setups where page title, meta data, and head markup are defined +centrally in a layout. + +.. literalinclude:: _codesnippets/_PageLayout.html + :caption: EXT:my_extension/Resources/Private/PageView/Layout/Default.html + +The example above combines several Page ViewHelpers, each responsible for a +specific page-level concern: + +* `Page.title ViewHelper `_ + Used to compose a dynamic document title from multiple values instead of + relying on the default page title. + +* `Page.meta ViewHelper `_ + Used to define SEO-related, OpenGraph, and Twitter / X meta tags directly + in the Fluid template. + +* `Page.headerData ViewHelper `_ + Used to inject additional markup into the HTML `` section, for + example favicon and touch icon definitions. + +In addition, the example uses format ViewHelpers to normalize content before +it is used in titles and meta tags: + +* `Format.stripTags ViewHelper `_ + Removes HTML markup from rich text values. + +* `Format.html ViewHelper `_ + Renders HTML content safely in the page body. diff --git a/Documentation/Global/Page/Meta.rst b/Documentation/Global/Page/Meta.rst index b185ea8..97f9862 100644 --- a/Documentation/Global/Page/Meta.rst +++ b/Documentation/Global/Page/Meta.rst @@ -1,7 +1,3 @@ -.. This reStructured text file has been automatically generated, do not change. -.. Source: https://github.com/TYPO3/typo3/blob/main/typo3/sysext/fluid/Classes/ViewHelpers/Page/MetaViewHelper.php - -:edit-on-github-link: https://github.com/TYPO3/typo3/edit/main/typo3/sysext/fluid/Classes/ViewHelpers/Page/MetaViewHelper.php :navigation-title: page.meta .. include:: /Includes.rst.txt @@ -12,5 +8,133 @@ Page.meta ViewHelper `` ==================================== +.. versionadded:: 14.0 + +.. typo3:viewhelper:: page.meta + :source: /Global.json + :display: tags, gitHubLink + :noindex: + +.. contents:: Table of contents + +The Fluid ViewHelper :html:`` allows meta tags to be defined +directly within Fluid templates by leveraging TYPO3's MetaTagManager API. + +This allows frontend rendering logic—such as Extbase plugins, Fluid-based +content elements, or site package templates—to control meta tags (for +example descriptions, OpenGraph data, and social media cards) directly in +Fluid templates, without requiring custom PHP logic. + +Meta tags can be defined and managed directly in Fluid templates, reducing +or eliminating the need for additional TypoScript configuration in many +common scenarios. + +.. _typo3-fluid-page-meta-usage-examples: + +Using the `` ViewHelper +=================================== + +The following examples demonstrate common use cases for the +:html:`` ViewHelper in frontend Fluid templates. They show how +meta tags can be defined, extended, and replaced directly in Fluid while +integrating with TYPO3's MetaTagManager system. + +.. _typo3-fluid-page-meta-example-detail-view: + +Set meta tags in a detail view template +-------------------------------------- + +Meta tags can be defined directly in a Fluid template, for example in a +detail view that renders a single domain object. + +.. code-block:: html + :caption: EXT:my_extension/Resources/Private/Templates/Item/Show.html + + {item.description} + {item.title} + article + +

{item.title}

+

{item.description}

+ + +.. _typo3-fluid-page-meta-example-opengraph: + +Define OpenGraph and Twitter / X Card meta tags +----------------------------------------------- + +OpenGraph and Twitter / X Card meta tags can be used to control how pages +are displayed when shared on social media platforms. + +.. code-block:: html + + My Article Title + Article description + + summary_large_image + + + +.. _typo3-fluid-page-meta-example-subproperties: + +Use sub-properties for complex meta tags +---------------------------------------- + +Some meta tags, such as image-related tags, support additional +sub-properties like dimensions or alternative text. + +.. code-block:: html + + + {item.image.url} + + + +.. _typo3-fluid-page-meta-example-custom-types: + +Define custom meta tag types +---------------------------- + +Custom meta tags can be defined by explicitly specifying the meta tag type +attribute. + +.. code-block:: html + + John Doe + + index, follow + + + +.. _typo3-fluid-page-meta-example-replace: + +Replace existing meta tags +-------------------------- + +Existing meta tags with the same property can be replaced explicitly when +required. + +.. code-block:: html + + + Override any existing description + + + +All examples shown above integrate with TYPO3's MetaTagManager system and +respect configured meta tag managers, priorities, and rendering rules. +This enables a template-centric approach to managing SEO-relevant meta +data that reflects the rendered content accurately. + +.. _typo3-fluid-page-meta-arguments: + +Arguments of the `` ViewHelper +=========================================== + +.. include:: /_Includes/_ArbitraryArguments.rst.txt + .. typo3:viewhelper:: page.meta - :source: ../../Global.json + :source: /Global.json + :display: arguments-only diff --git a/Documentation/Global/Page/_codesnippets/_PageLayout.html b/Documentation/Global/Page/_codesnippets/_PageLayout.html new file mode 100644 index 0000000..633e566 --- /dev/null +++ b/Documentation/Global/Page/_codesnippets/_PageLayout.html @@ -0,0 +1,31 @@ + +{page.title} - {page.subtitle} - {site.name} + + + {page.description -> f:format.stripTags()} + +{page.title} - {page.subtitle} - {site.name} +article + + {page.description -> f:format.stripTags()} + + + + + + + +

{page.title}

+{page.description -> f:format.html()} +
+ +