diff --git a/Documentation/FluidTemplates/FromTheScratch.rst b/Documentation/FluidTemplates/FromTheScratch.rst index c92cc5ca..084784fe 100644 --- a/Documentation/FluidTemplates/FromTheScratch.rst +++ b/Documentation/FluidTemplates/FromTheScratch.rst @@ -3,9 +3,9 @@ .. _fluid-templates-scratch: -================================ -Fluid Templates from the Scratch -================================ +============================ +Fluid Templates from Scratch +============================ .. contents:: diff --git a/Documentation/FluidTemplates/Index.rst b/Documentation/FluidTemplates/Index.rst index e9a658d8..1c708335 100644 --- a/Documentation/FluidTemplates/Index.rst +++ b/Documentation/FluidTemplates/Index.rst @@ -7,25 +7,25 @@ Fluid Templates =============== -To understand the following section you need basic knowledge about how to use the +To understand the following section you need basic knowledge of the :ref:`Fluid templating engine ` and :ref:`TypoScript `. -This chapter is based on the following steps: +This chapter assumes the following: * A Composer-based TYPO3 installation, at least version 13.4. * You have installed a `Generate a site package of type "Site Package Tutorial" `_, including the example page tree loaded in `Create initial pages `_. -* You have familiarized yourself with `Asset handling in TYPO3 `_ - (CSS, JavaScript, design related images, ...) +* You are familiar with `Asset handling in TYPO3 `_ + (CSS, JavaScript, design related images, etc) -After this tutorial you have a better understanding of the example templates and -how to adjust them to your needs. You should also be able to create some -templates yourself. +After this tutorial you will have a better understanding of Fluid templates and +how to customize them to your needs. You should also be able to create some +Fluid templates yourself. -If you prefer to start with a pure HTML template and build all templates -step by step, you can alternatively have a look a :ref:`fluid-templates-scratch`. +If you prefer to start with an HTML template and build it up to a Fluid template +step by step, have a look at :ref:`fluid-templates-scratch`. .. contents:: Topics covered in this chapter @@ -40,10 +40,10 @@ step by step, you can alternatively have a look a :ref:`fluid-templates-scratch` The page view ============= -The Fluid templates for the whole page have to be configured via TypoScript. +The Fluid templates that we will use to output the frontend pages have to be configured via TypoScript. -In the example site package that was `Generated for you `_ -the according TypoScript can be found in file +In the site package that was `Generated for you `_, +the TypoScript configuration can be found in :file:`packages/my_site_package/Configuration/Sets/SitePackage/TypoScript/page.typoscript`: .. literalinclude:: /CodeSnippets/my_site_package/Configuration/Sets/SitePackage/TypoScript/page.typoscript @@ -51,11 +51,11 @@ the according TypoScript can be found in file :linenos: :emphasize-lines: 3,6 -Line 3 defines that Fluid templates should be used for the page by using the -TypoScript object `PAGEVIEW `_. +Line 3 defines that Fluid templates should be configured using the +`PAGEVIEW `_ TypoScript object . -In line 6 the default path to the page view templates is defined. The definition -could be extended in line 7 by a setting later own. For now assume all Fluid +Line 6 defines the default path to the page view templates. We can add further +paths to the definition in line 7 with a site setting later on. For now assume all Fluid templates for the page can be found in folder :path:`packages/my_site_package/Resources/Private/PageView`. @@ -65,10 +65,11 @@ The default page template ========================= Unless a different page layout is chosen, `PAGEVIEW `_ -expects the main template of the page in file :file:`PageView/Pages/Default.html` within -the defined folder (:path:`packages/my_site_package/Resources/Private/PageView`). +expects the main template of the page to be :file:`PageView/Pages/Default.html` in +the folder :path:`packages/my_site_package/Resources/Private/PageView` (the path +that we defined above). -Let us have a look at this template now: +Let's have a look at this default page template: .. literalinclude:: /CodeSnippets/my_site_package/Resources/Private/PageView/Pages/Default.html :caption: packages/my_site_package/Resources/Private/PageView/Pages/Default.html @@ -76,67 +77,64 @@ Let us have a look at this template now: :emphasize-lines: 1,2,4 * In line 1 the `Layout ViewHelper `_ - is defined to load a layout template from folder :path:`PageView/Layouts`. The file - must have the same name of the templated, followed by `.html`, therefore - file :file:`packages/my_site_package/Resources/Private/PageView/Layouts/PageLayout.html` - is loaded as layout. -* Line 2 starts a new section with name "Main", using the + loads a layout template from the :path:`PageView/Layouts` folder. The layout + file is referred to by name, with an `.html` on the end. The layout file here is + :file:`packages/my_site_package/Resources/Private/PageView/Layouts/PageLayout.html`. +* Line 2 starts a section called "Main", using the `Section ViewHelper `_. -* In Line 4 and 7 partial templates are loaded from :path:`Partials`. They follow - the same naming scheme like the Layout and are therefore located in - files :file:`Documentation/CodeSnippets/my_site_package/Resources/Private/PageView/Partials/Content.html` - and :file:`Documentation/CodeSnippets/my_site_package/Resources/Private/PageView/Partials/Stage.html`. - To do this they use the `Render ViewHelper `_. +* Lines 4 and 7 load partial templates from the :path:`Partials` folder. They follow + the same naming scheme as the layout: they are located in + :file:`packages/my_site_package/Resources/Private/PageView/Partials/Content.html` + and :file:`packages/my_site_package/Resources/Private/PageView/Partials/Stage.html`. + The partials are loaded with the `Render ViewHelper `_. .. _layout-template: The Fluid layout template ========================= -The outer most HTML that is needed for all different page layouts is usually -defined in a layout template: +The outermost HTML on a page/pages is defined by a layout template: .. literalinclude:: /CodeSnippets/my_site_package/Resources/Private/PageView/Layouts/PageLayout.html :caption: /CodeSnippets/my_site_package/Resources/Private/PageView/Layouts/PageLayout.html :linenos: :emphasize-lines: 5 -The layout template takes care of loading assets like CSS and JavaScript that -are needed on all pages, using the `Asset collector `_. +The layout template takes care of loading assets that +are needed on all pages, like CSS and JavaScript. It uses the `Asset collector `_. -To configure the asset collector, the `Asset.css ViewHelper `_ -and `Asset.script ViewHelper `_ -are used. +The asset collector is configured using the `Asset.css ViewHelper `_ +and `Asset.script ViewHelper `_. -The layout also renders sections that need to be defined with the -`Section ViewHelper `_ -in the page template. In line 5 the section is rendered, which is defined in line -2-10 of the "Default" page template. It is possible to define several sections -and to define optional sections. We do not demonstrate that here. +Also, the layout template renders sections using a +`Section ViewHelper `_. +The sections are defined in the page template. The "Main" section in line 5 +is defined in lines 2-10 of the "Default" page template. It is possible to define +optional sections (not shown here). -The layout template also loads some more partials, for example to display +Our layout template also loads some partials, for example, to display the menu and the footer. .. _page-html-structure: -Outer most HTML structure (body, head) -====================================== +Outermost HTML structure (body, head) +===================================== -The outer most HTML structure is usually not handled by your custom templates. It -can be configured via the TypoScript configuration of the +The outermost HTML is not usually handled in Fluid templates. It +is configured via TypoScript configuration of the `PAGE `_ object. -For example you can use option :ref:`shortcutIcon ` -to load a favicon, :ref:`meta ` to define meta tags, -or add tags to the body tag using :ref:`bodyTagAdd `. +For example, you can use the :ref:`shortcutIcon ` +option to load a favicon, :ref:`meta ` to define meta tags, +and :ref:`bodyTagAdd ` to add tags to the body tag. -The page object, including examples is described in detail in the TypoScript -reference, chapter `Configure the PAGE in TypoScript `_. +The page object, including examples, is described in detail in the TypoScript +reference. See `Configure the PAGE in TypoScript `_. .. _partial-template: -The footer: Example for a partial template -========================================== +The footer: Example of a partial template +========================================= In the :ref:`layout template ` the following partial was loaded: @@ -145,22 +143,22 @@ In the :ref:`layout template ` the following partial was loaded :linenos: :emphasize-lines: 5-7,11 -Line 5 uses the `Link.page ViewHelper `_ -to link to the start page, which is the same like the root page and found in the -variable `{site.rootPageId}`. +Line 5 uses a `Link.page ViewHelper `_ +to link to the start page. The start page is the same as the root page and is found in the +`{site.rootPageId}` variable. The variable `{site}` is automatically provided by the -`PAGEVIEW `_. All -available variables are described in the TypoScript Reference, section +`PAGEVIEW `_ TypoScript object. All +variables are described in the TypoScript Reference. See `Default variables in Fluid templates `_. -Line 6 uses the `Image ViewHelper `_ +Line 6 uses an `Image ViewHelper `_ to display a logo in the footer. The path to the logo and its alt tag are -defined in the settings definition. More about this in chapter -`Setting definition `_. +defined in the site package settings definitions. See +`Setting definitions `_. -In line 11 yet another partial is included. This partial displays a menu in the -footer. More about this topic in chapter :ref:`Configure the menus `. +Line 11 adds another partial. This partial displays a menu in the +footer. See :ref:`Configuring the menus `. .. _fluid-templates-next-steps: