[DOC] Improve documentation on how to templating works

Fixes #45
fnagel · Jan 25, 2024 · 6babc28 · 6babc28
1 parent 43d625f
commit 6babc28
Show file tree

Hide file tree

Showing 5 changed files with 57 additions and 16 deletions.
diff --git a/Configuration/TypoScript/Examples/setup.typoscript b/Configuration/TypoScript/Examples/setup.typoscript
@@ -1,17 +1,24 @@
 plugin.tx_genericgallery.settings.gallery {
 	default {
+        # Name (for use in backend)
 		name = Default Gallery
 
-		# Icon
+		# Icon (for use in backend)
 		icon = extensions-generic-gallery
 
-		# Template for gallery
-		template = EXT:generic_gallery/Resources/Private/Templates/GalleryCollection/Show.html
+        # Templates, partials and layouts files configured by standard extbase / fluid config
+        # Templates for each gallery can be overridden by using the following configuration:
+        # "template = EXT:my_ext/Resources/Private/Templates/SomeFolder/SomeFile.html"
+        # Otherwise the extension will use your "view.templateRootPaths" configuration
+        # together with the default template path as described below
 
-		# Template for item detail view
-		itemTemplate = EXT:generic_gallery/Resources/Private/Templates/GalleryItem/Show.html
+		# Template for gallery view (default: "GalleryCollection/Show.html")
+		template =
 
-		# Pagination configuration for gallery
+		# Template for gallery item detail view (default: "GalleryItem/Show.html")
+		itemTemplate =
+
+		# Pagination configuration
 		paginate {
 			itemsPerPage = 8
 			insertAbove = 0

diff --git a/Configuration/TypoScript/setup.typoscript b/Configuration/TypoScript/setup.typoscript
@@ -1,4 +1,5 @@
 plugin.tx_genericgallery {
+    # Please see documentation for custom templating configuration!
 	view {
 		templateRootPaths.0 = EXT:generic_gallery/Resources/Private/Templates/
 		templateRootPaths.10 = {$plugin.tx_genericgallery.view.templateRootPath}
@@ -11,9 +12,7 @@ plugin.tx_genericgallery {
 	}
 
 	settings {
-		# Partial and layout files configured by standard extbase / fluid config, see above
-
-		# Config available gallery types
+		# Config available gallery types (see documentation or examples for more info)
 		gallery {
 
 		}

diff --git a/Documentation/Configuration/Template/Index.rst b/Documentation/Configuration/Template/Index.rst
@@ -6,18 +6,36 @@
 Templating
 ^^^^^^^^^^
 
+This extension uses Extbase / Fluid default functionality for templating, even though, there is come custom configuration to handle gallery types.
+
+So by default, TYPO3 will search in the default template root path of the extension: `EXT:generic_gallery/Resources/Private/Templates/GalleryCollection/Show.html`
+
+If you change the template path like this: `plugin.tx_genericgallery.view.templateRootPaths.0 = EXT:my_extension/Resources/Private/Templates/GenericGallery/`,
+TYPO3 will search for `EXT:my_extension/Resources/Private/Templates/GenericGallery/GalleryCollection/Show.html`.
+
+
+**How to configure the template file for each gallery type**
+
+This extension allows to define multiple gallery types. Each gallery type needs a custom template file.
+To accomplish this, there are two TypoScript settings: `template` and `templateItem` (used for the item detail view)
+
+You can change the path for each gallery type by using the following TS:
+`plugin.tx_genericgallery.settings.gallery.myGalleryType.template = EXT:my_extension/Resources/Private/Templates/SomeFolder/SomeFile.html`
+
+See the example TypoScript files for more info!
+
+
 .. tip::
 
-	Since version 1.0.0 Generic Gallery uses fluid as templating engine.
-	This means you will need to recreate your templates when updating from previous versions.
+   When using more than one gallery type, you should always use `template` (and `templateItem`) TS settings
+   in order to configure the template file for each gallery type!
 
-	It's still possible to use grouped elements. For example four items wrapped in a :code:`<div>`.
-	There's a view helper for that.
 
 
 .. _configuration-template:
 
-**Available variables**
+Available variables
+"""""""""""""""""""
 
 - `uid`: current plugin content element UID (localized)
 - `galleryType`: current plugin gallery type (single, images, collection)

diff --git a/Documentation/Configuration/Typoscript/Index.rst b/Documentation/Configuration/Typoscript/Index.rst
@@ -37,8 +37,8 @@ Properties
    view.layoutRootPath_                                  :ref:`t3tsref:data-type-string`                                       no                      :code:`EXT:generic_gallery/Resources/Private/Layouts/`
    settings.gallery_                                     array                                       						   no
    settings.gallery.name_                                :ref:`t3tsref:data-type-string`                                       no
-   settings.gallery.template_                            :ref:`t3tsref:data-type-string`                                       no
-   settings.gallery.itemTemplate_                        :ref:`t3tsref:data-type-string`                                       no                      :code:`EXT:generic_gallery/Resources/Private/Templates/GalleryItem/Show.html`
+   settings.gallery.template_                            :ref:`t3tsref:data-type-string`                                       no                      Fallback to Extbase's' default behavior
+   settings.gallery.itemTemplate_                        :ref:`t3tsref:data-type-string`                                       no                      Fallback to Extbase's' default behavior
    ===================================================== ===================================================================== ======================= ==================
 
 
@@ -97,6 +97,10 @@ settings.gallery.template
 :typoscript:`plugin.tx_genericgallery.settings.gallery.template =` :ref:`t3tsref:data-type-string`
 
 Define a template file for this gallery type.
+Use something like `EXT:my_extension/Resources/Private/Templates/SomeFolder/SomeFile.html`
+
+If not set, the Extbase's default behavior will be used:
+TYPO3 uses the template root path from `plugin.tx_genericgallery.view.templateRootPaths` and adds `GalleryCollection/Show.html` to it.
 
 
 settings.gallery.itemTemplate
@@ -105,3 +109,7 @@ settings.gallery.itemTemplate
 :typoscript:`plugin.tx_genericgallery.settings.gallery.itemTemplate =` :ref:`t3tsref:data-type-string`
 
 Define a detail view template file for this gallery type.
+Use something like `EXT:my_extension/Resources/Private/Templates/SomeFolder/SomeFile.html`
+
+If not set, the Extbase's default behavior will be used:
+TYPO3 uses the template root path from `plugin.tx_genericgallery.view.templateRootPaths` and adds `GalleryItem/Show.html` to it.
diff --git a/Documentation/UpgradeGuide/Index.rst b/Documentation/UpgradeGuide/Index.rst
@@ -442,6 +442,15 @@ records to FAL. This task exceeds the scope of this documentation.
 See demos: :code:`/Configuration/TypoScript/Examples`
 
 
+.. tip::
+
+	Since version 1.0.0 Generic Gallery uses fluid as templating engine.
+	This means you will need to recreate your templates when updating from previous versions.
+
+	It's still possible to use grouped elements. For example four items wrapped in a :code:`<div>`.
+	There's a view helper for that.
+
+
 .. tip::
 
 	You will need to install EXT:filemetadata and EXT:metadata in order to use EXIF data