[FEATURE] Create a minimal site package

Documentation/Index.rst

@@ -49,13 +49,11 @@ A working copy of the site package extension can be retrieved from the
         ..  card-footer:: :ref:`Create some dummy content <t3sitepackage:typo3-backend-create-initial-pages>`
             :button-style: btn btn-secondary stretched-link
 
-    ..  card:: :ref:`Minimal example <t3sitepackage:minimal-design>`
+    ..  card:: :ref:`Minimal site package <t3sitepackage:minimal-design>`
 
-        We explain how you can easily show some text in the frontend. The
-        example explains how to use TypoScript to output text in the
-        frontend.
+        Create a minimal site package that outputs "Hello World".
 
-        ..  card-footer:: :ref:`See the minimal example <t3sitepackage:minimal-design>`
+        ..  card-footer:: :ref:`Create a minimal site package <t3sitepackage:minimal-design>`
             :button-style: btn btn-secondary stretched-link
 
     ..  card:: :ref:`Design Template <t3sitepackage:dt-external-resources>`

Documentation/MinimalExample/Index.rst

@@ -3,98 +3,184 @@
 
 .. _minimal-design:
 
-===============
-Minimal example
-===============
+====================
+Minimal site package
+====================
 
-We want to create a site package that outputs a single web page with
-minimal effort. This site package can be used to simply test system output or as
-an example of the fewest possible steps to create a working 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.
 
-To start, in the TYPO3 backend, create a standard page named
-:guilabel:`Minimal example` just under (inside) the page tree TYPO3 logo
-container. Create a new TypoScript template record on this page.
-Give the TypoScript template a title, and make it a root level template,
-but do not include any static templates.
+So first we create a minimal extension.
+
+.. _minimal-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"):
+     > t3docs/site-package
+
+     Enter the extension key [site_package]:
+     >
+
+     Enter the PSR-4 namespace [T3docs/SitePackage]:
+     >
+
+     Choose supported TYPO3 versions (comma separate for multiple) [TYPO3 v12 LTS]:
+      [10] TYPO3 v10 LTS
+      [11] TYPO3 v11 LTS
+      [12] TYPO3 v12 LTS
+      [13] TYPO3 v13
+     > 13
+
+     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
+(`t3docs/site-package`) and the extension name (`site_package`).
+
+In order to see a change in the TYPO3 backend or frontend your site package needs
+to be :ref:`installed <extension-installation>`.
+
+After you have created your site package extension you can uninstall :composer:`b13/make`:
+
+..  code-block:: bash
+
+    ddev composer remove b13/make --dev
+
+.. _minimal-extension-siteset:
+
+Create a basic site set
+=======================
+
+..  versionadded:: 13.1
+    :ref:`Site sets <t3coreapi:site-sets>` have been introduced.
+
+Create a folder called :path:`Configuration/Sets/Minimal/` in the site package
+and add a file called :file:`config.yaml` to it. This file contains the
+**site set** of your site package:
+
+..  literalinclude:: _config.yaml
+    :caption: packages/site-package/Configuration/Sets/Minimal/config.yaml
+
+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:
+
+..  figure:: AddSiteSet.png
+    :alt: Screenshot demonstrating adding the "Minimal example site package" to the site main
+
+    Use module :guilabel:`Site Management > Sites` to add the "Minimal example site package"
+
+On saving, the site package is added to your site configuration file, which changes to this:
+
+..  literalinclude:: _config.yaml.diff
+
+.. _minimal-extension-typoscript:
 
 The TypoScript-only version
 ===========================
 
-In the TypoScript template Setup field, add the following three lines:
+..  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`:
 
-.. code-block:: typoscript
-   :caption: TypoScript Setup
+..  literalinclude:: _minimal.typoscript
+    :caption: packages/site-package/Configuration/Sets/Minimal/setup.typoscript
 
-   page = PAGE
-   page.1 = TEXT
-   page.1.value = Hello, world.
+Clear all caches and preview the web page.
 
-View the web page.
+You can learn more about the TypoScript syntax used here in chapter
+:ref:`A minimal page created by pure TypoScript <t3start:typoscript>`
+of the "Getting Started Tutorial".
 
-This TypoScript-only design has the least instructions required to output a
-web page from TYPO3. This TypoScript template is self contained and
-no other files or database records needed. Changing this content
-only requires the appropriate access needed to make changes to TypoScript
-templates.
+.. _minimal-extension-fluid:
 
 The TYPO3 Fluid version
 =======================
 
-Empty the :guilabel:`Minimal design` page TypoScript template Setup field,
-then add the following lines:
+Replace file :file:`setup.typoscript` of example
+:file:`minimal-extension-typoscript` with the following lines:
 
-.. code-block:: typoscript
-   :caption: TypoScript Setup
+..  literalinclude:: _pageview.typoscript
+    :caption: packages/site-package/Configuration/Sets/Minimal/setup.typoscript
+    :linenos:
 
-   page = PAGE
-   page.1 = FLUIDTEMPLATE
-   page.1.file = EXT:site_package/Resources/Private/Templates/Minimal.html
+If you preview your page now you would get an error output like:
 
-Create a file named :file:`Minimal.html` in a
-:file:`typo3conf/ext/site_package/Resources/Private/Templates` folder.
+..  code-block:: html
 
-The site package extension has to be :ref:`installed <extension-installation>`
-and requires a :ref:`minimal composer configuration <extension-configuration>` (if composer is used)
-for this to work
+    Oops, an error occurred! Request: bddd8a816bda3
 
-.. code-block:: html
-   :caption: EXT:site_package/Resources/Private/Templates/Minimal.html
+.. todo: Add information about dealing with errors such as these and link from here.
+
+This is because the template has not been found.
 
-   Hello, world.
+By searching for the hash `bddd8a816bda3` in the log file you will find such an entry:
 
-Now view the web page.
+..  code-block:: plaintext
+    :caption: var/log/typo3_ece44d5005.log
+    :emphasize-lines: 7
 
-Here we are putting the page content into a separate HTML file, allowing for
-separate access control and for an editing workflow that does not need much
-TypoScript. The TYPO3 renderer still requires a TypoScript template on the
-:guilabel:`Minimal design` page to know which file to process.
+    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/t3docs/site-package/Resources/Private/Templates/
 
-Resulting web page
-==================
+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.
 
-Here is the resulting web page HTML source for both the TypoScript-only and
-the Fluid based implementations. Notice how TYPO3 has added default markup
-around the single line of content:
+Create a file named :file:`Default.html` in folder
+:path:`packages/site-package/Resources/Private/Pages`.
 
 .. code-block:: html
-   :caption: Example frontend output
-
-   <!DOCTYPE html>
-   <html lang="en">
-      <head>
-         <meta charset="utf-8">
-         <!--
-            This website is powered by TYPO3 - inspiring people to share!
-            TYPO3 is a free open source Content Management Framework initially
-            created by Kasper Skaarhoj and licensed under GNU/GPL.
-            TYPO3 is copyright 1998-2018 of Kasper Skaarhoj. Extensions are
-            copyright of their respective owners.
-            Information and contribution at https://typo3.org/
-         -->
-         <title>Minimal design</title>
-         <meta name="generator" content="TYPO3 CMS">
-      </head>
-      <body>
-         Hello, world.
-      </body>
-   </html>
+   :caption: packages/site-package/Resources/Private/Pages/Default.html
+
+   Hello Fluid World!
+
+Clear all caches and preview the web page.
+
+Learn more about using Fluid Templates in chapter :ref:`fluid-templates`.

Documentation/MinimalExample/_config.yaml

@@ -0,0 +1,2 @@
+name: t3docs/site-package-minimal
+label: "Example: Minimal site package"

Documentation/MinimalExample/_config.yaml.diff

@@ -0,0 +1,5 @@
+ base: '/'
++dependencies:
++  - t3docs/site-package
+ languages:
+    # ...

Documentation/MinimalExample/_minimal.typoscript

@@ -0,0 +1,7 @@
+# Create the frontend output of the page
+page = PAGE
+page {
+    # Show a text with value "Hello TypoScript World!"
+    10 = TEXT
+    10.value = Hello TypoScript World!
+}

Documentation/MinimalExample/_pageview.typoscript

@@ -0,0 +1,9 @@
+page = PAGE
+page {
+    10 = PAGEVIEW
+    10 {
+        paths {
+            100 = EXT:site_package/Resources/Private/Templates/
+        }
+    }
+}