[TASK] Site package tutorial depends on Site Package Builder (#306)

Explain how to read the generated files instead of
having readers create them themselves.

Releases: main, 13.4

Author: linawolf

Documentation/ContentMapping/Index.rst

@@ -153,7 +153,7 @@ You can debug this variable in the main section of your template using the
 The debug output after clearing all caches and previewing the page should look
 like this:
 
-..  figure:: _images/contents_debug.png
+..  figure:: /Images/ContentMapping/contents_debug.png
     :alt: Screenshot of the debug output of {content}
 
     The debug output should contain sections "stage" and "main"

Documentation/MinimalExample/Index.rst

@@ -1,162 +1,40 @@
-.. include:: /Includes.rst.txt
-.. highlight:: typoscript
+..  include:: /Includes.rst.txt
+..  highlight:: typoscript
 
-.. _minimal-design:
+..  _minimal-design:
 
-====================
-Minimal site package
-====================
+=======================
+Generate a site package
+=======================
 
 A site package is a custom TYPO3 extension which contains configuration,
 templates, assets, etc that are used for the site it belongs to.
 
-So first we create a minimal extension.
+So first we generate a minimal extension.
 
 ..  contents::
 
 .. _minimal-extension:
-
-Create a minimal TYPO3 extension manually
-=========================================
-
-Create the following file in the folder `packages` in your TYPO3 installation:
-
-..  code-block:: json
-    :caption: packages/my-site-package/composer.json
-    :linenos:
-
-    {
-    	"name": "myvendor/my-site-package",
-    	"type": "typo3-cms-extension",
-    	"description": "My site package",
-    	"require": {
-    		"typo3/cms-core": "^13.4"
-    	},
-        "autoload": {
-            "psr-4": {
-                "Myvendor\\MySitePackage\\": "Classes/"
-            }
-        },
-    	"extra": {
-    		"typo3/cms": {
-    			"extension-key": "my_site_package"
-    		}
-    	}
-    }
-
-In order to see any changes in the TYPO3 backend or frontend your site package
-needs to be :ref:`installed <extension-installation>`:
-
-..  code-block:: bash
-
-    ddev composer req myvendor/my-site-package
-
-..  note::
-    The Composer name in this example is `myvendor/my-site-package`. Use this
-    name for all Composer commands like `ddev composer req myvendor/my-site-package`.
-
-    `my_site_package` is the extension name. For historical reasons all dashes need
-    to be converted to underscores and the vendor name removed. This name is used
-    to reference files, for example `packages/my_site_package/Resources/Public/Css/my.css`.
-
-
-.. _minimal-b13-make-extension:
-
-Create a minimal TYPO3 extension using b13/make
-===============================================
-
-:composer:`b13/make` is a convenient TYPO3 extension which you can use during
-development to create a new TYPO3 extension quickly or add functionality to an
-existing one.
-
-Use Composer to install it for development only:
-
-..  code-block:: bash
-
-    ddev composer req b13/make --dev
-
-Execute the command `ddev typo3 make:extension` and answer the prompt
-
-..  code-block:: bash
-
-    ddev typo3 make:extension
-
-     Enter the composer package name (e.g. "vendor/awesome"):
-     > myvendor/my-site-package
-
-     Enter the extension key [my_site_package]:
-     >
-
-     Enter the PSR-4 namespace [Myvendor/MySitePackage]:
-     >
-
-     Choose supported TYPO3 versions (comma separate for multiple) [TYPO3 v12 LTS]:
-      [10.4] TYPO3 v10 LTS
-      [11.5] TYPO3 v11 LTS
-      [12.4] TYPO3 v12 LTS
-      [13.4] TYPO3 v13 LTS
-     > 13.4
-
-     Enter a description of the extension:
-     > My site package
-
-     Where should the extension be created? [src/extensions/]:
-     > packages
-
-     May we add a basic service configuration for you? (yes/no) [yes]:
-     > no
-
-     May we create a ext_emconf.php for you? (yes/no) [no]:
-     >
-
-     [OK] Successfully created the extension my_site_package (myvendor/my-site-package).
-
-This script creates a new folder called `packages` with a subfolder,
-`my-site-package`. It mainly contains only a file called `composer.json`.
-
-You could of course also create this file manually. Step
-:ref:`extension-configuration-composer` will explain the content of the :file:`composer.json`.
-For the time being just remember the Composer name you have chosen
-(`myvendor/my-site-package`) and the extension name (`my_site_package`).
-
-In order to see any changes in the TYPO3 backend or frontend your site package
-needs to be :ref:`installed <extension-installation>`:
-
-..  code-block:: bash
-
-    ddev composer req myvendor/my-site-package
-
-After you have created your site package extension you can uninstall :composer:`b13/make`:
-
-..  code-block:: bash
-
-    ddev composer remove b13/make --dev
-
 .. _minimal-site-package-builder:
 
-Create a minimal TYPO3 extension using the Site Package Builder
-===============================================================
-
-To quickly build a site package you can also use the
-`Sitepackage Builder <https://get.typo3.org/sitepackage>`__.
+Generate and download a site package
+====================================
 
-To follow this tutorial you can fill in the form like that:
+You can download a site package by using the official Site Package Builder at
+https://get.typo3.org/sitepackage or by using curl.
 
-..  figure:: SitePackageGeneratorForm.png
-    :alt: Form fields to generate the tutorial package site
-    :caption: Form fields to generate the tutorial package site
+You have the choice of three site packages types:
 
-The summary of your data is then displayed.
+*   Bootstrap Package: This site package comes with a ready to use theme
+*   Fluid Styled Content: A minimal site package where you can build your own
+    custom theme.
+*   Site Package Tutorial: Contains all files that are used as examples in
+    this tutorial.
 
-..  figure:: SitePackageGeneratorSummary.png
-    :alt: Summary of information provided
-    :caption: Summary of information provided
+To follow this tutorial, chose "Site Package Tutorial" as type of the site package.
 
-You have to click on the "Download" link, on the top of the summary
-in order to get your zipped site package.
-
-You can then unzip the zip file, place the resulting folder in your
-`packages` folder, and :ref:`install it <extension-installation>`.
+Download and unzip the zip file, place the result in folder
+`packages/my_site_package`, and :ref:`install it <extension-installation>`.
 
 .. _extension-installation:
 
@@ -176,24 +54,27 @@ followed these steps:
 Install the site package you just created
 -----------------------------------------
 
-Move your extension folder :path:`my-site-package/` into the :path:`packages/`
+If you used the Site Package Builder, file :file:`packages/my_site_package/README.md`
+contains instructions on how to install your site package.
+
+Move / unzip your extension folder :path:`my_site_package/` into the :path:`packages/`
 folder. Then *require* the extension via Composer using the
 package name defined in the site package extension's :file:`composer.json` now located
-at :file:`packages/my-site-package/`
+at :file:`packages/my_site_package/`
 
 .. code-block:: json
    :caption: packages/my-site-package/composer.json
 
    {
-      "name": "myvendor/my-site-package"
+      "name": "my-vendor/my-site-package"
    }
 
 require it by:
 
-.. code-block:: bash
+..  code-block:: bash
    :caption: Execute in directory page_root
 
-    composer require myvendor/my-site-package:@dev
+    ddev composer require my-vendor/my-site-package:@dev
 
 ..  _extension-installation-project-structure:
 
@@ -214,13 +95,13 @@ Your project should now have the following structure:
 
         *   sites
 
-            *   :ref:`[site identifier] <typo3-backend-site>`
+            *   main
 
                 *   config.yaml
 
     *   packages
 
-        *   my-site-package
+        *   my_site_package
 
             *   [All sitepackage files]
 
@@ -246,56 +127,63 @@ Your project should now have the following structure:
     *   composer.json
     *   composer.lock
 
-
 .. _minimal-extension-siteset:
 
-Create a basic site set
-=======================
+Look at the a basic site set
+============================
 
 ..  versionadded:: 13.1
     :ref:`Site sets <t3coreapi:site-sets>` have been introduced.
 
-Create a folder called :path:`Configuration/Sets/SitePackage/` in the site package
-and add a file called :file:`config.yaml` to it. This file contains the
-**site set** of your site package:
+The site package build by Site Package Builder comes with a ready to use
+site set in folder :path:`packages/my_site_package/Configuration/Sets/SitePackage/`.
+
+The set itself is defined within this folder in the file :file:`config.yaml`:
 
-..  literalinclude:: _config.yaml
+..  literalinclude:: /CodeSnippets/my_site_package/Configuration/Sets/SitePackage/config.yaml
     :caption: packages/my-site-package/Configuration/Sets/SitePackage/config.yaml
+    :emphasize-lines: 1-2
 
 You will learn more about site sets in chapter
 :ref:`site_set`.
 
 You can find the complete reference in TYPO3 explained:
 :ref:`Site sets <t3coreapi:site-sets>`.
 
-Edit the site configuration that was created in step :ref:`typo3-backend-site`
-and add the site set to it. You can do this by using the backend module:
+During installation of your site package a page tree with example content was
+created, and should already have a site configuration in folder
+:path:`config/sites/main`.
+
+When you look at the site configuration in module :guilabel:`Site Management > Sites`
+it should already contain the set "My Site package". Other sets, for example
+if you want to use :composer:`typo3/cms-form` can be added here.
 
 ..  figure:: AddSiteSet.png
-    :alt: Screenshot demonstrating adding the "Example: My Site package" to the site main
+    :alt: Screenshot demonstrating adding the "My Site package" to the site main
 
     Use module :guilabel:`Site Management > Sites` to add the "Example: My Site package"
 
-On saving, the site package is added to your site configuration file, which changes to this:
+If you made no changes, the site configuration should look like this:
 
-..  literalinclude:: _config.yaml.diff
+..  literalinclude:: /CodeSnippets/my_site_package/Initialisation/Site/main/config.yaml
+    :caption: config/sites/main/config.yaml
 
 .. _minimal-extension-typoscript:
 .. _make-typoscript-available:
 
-The TypoScript-only version
-===========================
+The site set as TypoScript Provider
+===================================
 
 ..  versionadded:: 13.1
     A site set can be used as :ref:`TypoScript provider <t3coreapi:site-sets-typoscript>`.
 
-Create a file called :file:`setup.typoscript` containing basic TypoScript configuration
-in the folder of the site set you created in step :ref:`minimal-extension-siteset`:
-
-..  literalinclude:: _minimal.typoscript
-    :caption: packages/my-site-package/Configuration/Sets/SitePackage/setup.typoscript
+TYPO3 uses TypoScript as configuration language. The TypoScript is used to
+configure the templates, which are created with the templating language Fluid.
 
-Clear all caches and preview the web page.
+A file called :path:`packages/my_site_package/Configuration/Sets/SitePackage/setup.typoscript`
+provides the TypoScript to your site. This file contains imports of files from
+folder :path:`packages/my_site_package/Configuration/Sets/SitePackage/TypoScript`
+which contain the actual configuration.
 
 You can learn more about the TypoScript syntax used here in chapter
 :ref:`A minimal page created by pure TypoScript <t3start:typoscript>`
@@ -306,49 +194,16 @@ of the "Getting Started Tutorial".
 The TYPO3 Fluid version
 =======================
 
-Replace file :file:`setup.typoscript` of previuous example with the following lines:
+File :path:`packages/my_site_package/Configuration/Sets/SitePackage/TypoScript/page.typoscript`
+Defines how the output of all pages of the site is rendered with Fluid templates:
 
-..  literalinclude:: _pageview.typoscript
-    :caption: packages/my-site-package/Configuration/Sets/SitePackage/setup.typoscript
+..  literalinclude:: /CodeSnippets/my_site_package/Configuration/Sets/SitePackage/TypoScript/page.typoscript
+    :caption: packages/my_site_package/Configuration/Sets/SitePackage/TypoScript/page.typoscript
+    :emphasize-lines: 6
     :linenos:
 
-If you preview your page now you would get an error output like:
-
-..  code-block:: html
-
-    Oops, an error occurred! Request: bddd8a816bda3
-
-.. todo: Add information about dealing with errors such as these and link from here.
-
-This is because the template has not been found.
-
-By searching for the hash `bddd8a816bda3` in the log file you will find such an entry:
-
-..  code-block:: plaintext
-    :caption: var/log/typo3_ece44d5005.log
-    :emphasize-lines: 7
-
-    Mon, 07 Oct 2024 04:09:44 +0000 [ALERT] request="bddd8a816bda3"
-    component="TYPO3.CMS.Frontend.ContentObject.Exception.ProductionExceptionHandler":
-    Oops, an error occurred! Request: bddd8a816bda3- InvalidTemplateResourceException:
-    Tried resolving a template file for controller action "Default->Pages/Default"
-    in format ".html", but none of the paths contained the expected template file
-    (Default/Pages/Default.html).
-    The following paths were checked: /var/www/html/vendor/myvendor/my-site-package/Resources/Private/PageView/
-
-This error message also tells you the path where TYPO3 expects to find the file. If no path
-is listed here, the path defined in line 6 of the TypoScript above is incorrect,
-for example if you mistyped the extension name or part of the path.
-
-Create a file named :file:`Default.html` in folder
-:path:`packages/my-site-package/Resources/Private/PageView/Pages`.
-
-.. code-block:: html
-   :caption: packages/my-site-package/Resources/Private/PageView/Pages/Default.html
-
-   Hello Fluid World!
-
-Clear all caches and preview the web page.
+Line 6 defines from what directory the Fluid Templates are loaded. Line 7 allows
+to override this part via settings.
 
 Learn more about using Fluid Templates in chapter :ref:`fluid-templates`.
 
@@ -382,7 +237,7 @@ a file called :file:`composer.json` was created for you:
     :linenos:
 
 At the top of the :file:`composer.json` file we see the Composer package name
-`myvendor/my-site-package` (with a dash) and at the bottom we see the TYPO3
+`my-vendor/my-site-package` (with a dash) and at the bottom we see the TYPO3
 extension key in the extra section - :file:`my_site_package` (with an underscore).
 The Composer "name" consists of a vendor name followed by a forward slash and the
 lowercase extension name with dashes.