[FEATURE] Create a minimal site package (#189)

The information on how to create a minimial TypoScript output without a site package was moved to Getting started: TYPO3-Documentation/TYPO3CMS-Tutorial-GettingStarted#422 As this is the site package tutorial, add an example of a minimal site package instead. Releases: main * Apply suggestions from code review Co-authored-by: Sarah McCarthy <[email protected]> --------- Co-authored-by: Sarah McCarthy <[email protected]> (cherry picked from commit 4e282b8)
TYPO3-Documentation · Oct 14, 2024 · 6a737dd · 6a737dd
1 parent 69f5ba9
commit 6a737dd
Show file tree

Hide file tree

Showing 4 changed files with 138 additions and 74 deletions.
diff --git a/Documentation/Index.rst b/Documentation/Index.rst
@@ -40,13 +40,11 @@ A working copy of the site package extension can be retrieved from the
         ..  card-footer:: :ref:`See the prerequisites <t3sitepackage:prerequisites>`
             :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>`

diff --git a/Documentation/MinimalExample/Index.rst b/Documentation/MinimalExample/Index.rst
@@ -3,98 +3,148 @@
 
 .. _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
+     > 12
+
+     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-typoscript:
 
 The TypoScript-only version
 ===========================
 
-In the TypoScript template Setup field, add the following three lines:
+Create a file called :file:`setup.typoscript` containing basic TypoScript configuration
+in the folder :path:`Configuration/Setup`:
 
-.. code-block:: typoscript
-   :caption: TypoScript Setup
+..  literalinclude:: _minimal.typoscript
+    :caption: packages/site-package/Configuration/TypoScript/Setup/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: ackages/site-package/Configuration/TypoScript/Setup/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`.
diff --git a/Documentation/MinimalExample/_minimal.typoscript b/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!
+}
diff --git a/Documentation/MinimalExample/_pageview.typoscript b/Documentation/MinimalExample/_pageview.typoscript
@@ -0,0 +1,9 @@
+page = PAGE
+page {
+    10 = PAGEVIEW
+    10 {
+        paths {
+            100 = EXT:site_package/Resources/Private/Templates/
+        }
+    }
+}