diff --git a/Documentation/ExtensionInstallation/Index.rst b/Documentation/ExtensionInstallation/Index.rst deleted file mode 100644 index 6a500dd3..00000000 --- a/Documentation/ExtensionInstallation/Index.rst +++ /dev/null @@ -1,123 +0,0 @@ -.. include:: /Includes.rst.txt - -.. _extension-installation: - -====================== -Extension installation -====================== - -This tutorial assumes that your TYPO3 instance is a brand new installation, -without any themes, templates, pages or content. - -We assume that you are working on your local machine using DDEV and that you -followed these steps: - -:ref:`Installing TYPO3 with DDEV ` - -.. contents:: - -.. _extension-installation_with_composer: - -Install the site package you just created -========================================= - -From all extensions, including our site package extension, must be installed -via Composer. - -As a site package is created with site-specific files it is usually best to keep -the files together in a version control system such as Git. - -Create a directory for local version-controlled extensions at the -root-level of your installation. The name is arbitrary, we use -:file:`packages/` here. - -Then edit your :file:`composer.json` in the root of your installation directory -to add the path as a local repository. - -Add the following lines: - -.. code-block:: json - :caption: page_root/composer.json - - { - "name": "myvendor/mysite", - "repositories": [ - { - "type": "path", - "url": "./packages/*" - } - ], - "require": { - "typo3/cms-core": "^13.1", - "..." : "..." - }, - "..." : "..." - } - -Move your extension folder :path:`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/site_package/` - -.. code-block:: json - :caption: packages/site_package/composer.json - - { - "name": "myvendor/site-package" - } - -require it by: - -.. code-block:: bash - :caption: Execute in directory page_root - - composer require myvendor/site-package:@dev - -Project file structure -====================== - -Your project should now have the following structure: - -.. directory-tree:: - :level: 1 - :show-file-icons: true - - * .ddev - - * :ref:`[Some configuration] ` - - * config - - * sites - - * :ref:`[site identifier] ` - - * config.yaml - - * packages - - * site_package - - * [All sitepackage files] - - * composer.json - - * public - - * fileadmin - - * [Images for content, PDFs, ...] - - * [public files needed by TYPO3] - - * var - - * log - * [private files needed by TYPO3] - - * vendor - - * [All installed packages, including TYPO3 source] - - * composer.json - * composer.lock diff --git a/Documentation/MinimalExample/Index.rst b/Documentation/MinimalExample/Index.rst index 3ad807d8..5d8e0542 100644 --- a/Documentation/MinimalExample/Index.rst +++ b/Documentation/MinimalExample/Index.rst @@ -36,12 +36,12 @@ Execute the command `ddev typo3 make:extension` and answer the prompt ddev typo3 make:extension Enter the composer package name (e.g. "vendor/awesome"): - > t3docs/site-package + > myvendor/my-site-package - Enter the extension key [site_package]: + Enter the extension key [my_site_package]: > - Enter the PSR-4 namespace [T3docs/SitePackage]: + Enter the PSR-4 namespace [Myvendor/MySitePackage]: > Choose supported TYPO3 versions (comma separate for multiple) [TYPO3 v12 LTS]: @@ -66,12 +66,12 @@ Execute the command `ddev typo3 make:extension` and answer the prompt [OK] Successfully created the extension my_site_package (myvendor/my-site-package). This script creates a new folder called `packages` with a subfolder, -`site-package`. It mainly contains only a file called `composer.json`. +`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`). +(`myvendor/my-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 `. @@ -83,16 +83,131 @@ After you have created your site package extension you can uninstall :composer:` ddev composer remove b13/make --dev Before your brand new site package extension takes effect in your TYPO3 -installation, you have to install it. First you have to edit your composer.json in the root of your installation directory to add `packages` as a local repository. +installation, you have to install it. First you have to edit your composer.json in the root of your installation directory to add `packages` as a local repository. -See also chapter :ref:`Extension installation `. -Then you can install your sitepackage with: +.. include:: /Includes.rst.txt -.. code-block:: bash +.. _extension-installation: + +Extension installation +====================== + +This tutorial assumes that your TYPO3 instance is a brand new installation, +without any themes, templates, pages or content. + +We assume that you are working on your local machine using DDEV and that you +followed these steps: + +:ref:`Installing TYPO3 with DDEV ` + +.. contents:: + +.. _extension-installation_with_composer: + +Install the site package you just created +----------------------------------------- + +From all extensions, including our site package extension, must be installed +via Composer. + +As a site package is created with site-specific files it is usually best to keep +the files together in a version control system such as Git. + +Create a directory for local version-controlled extensions at the +root-level of your installation. The name is arbitrary, we use +:file:`packages/` here. + +Then edit your :file:`composer.json` in the root of your installation directory +to add the path as a local repository. + +Add the following lines: + +.. code-block:: json + :caption: page_root/composer.json + + { + "name": "myvendor/mysite", + "repositories": [ + { + "type": "path", + "url": "./packages/*" + } + ], + "require": { + "typo3/cms-core": "^13.4", + "..." : "..." + }, + "..." : "..." + } + +Move 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/` + +.. code-block:: json + :caption: packages/my-site-package/composer.json + + { + "name": "myvendor/my-site-package" + } + +require it by: + +.. code-block:: bash + :caption: Execute in directory page_root + + composer require myvendor/my-site-package:@dev + +Project file structure +---------------------- + +Your project should now have the following structure: + +.. directory-tree:: + :level: 1 + :show-file-icons: true + + * .ddev + + * :ref:`[Some configuration] ` + + * config + + * sites + + * :ref:`[site identifier] ` + + * config.yaml + + * packages + + * site_package + + * [All sitepackage files] + + * composer.json + + * public + + * fileadmin + + * [Images for content, PDFs, ...] + + * [public files needed by TYPO3] + + * var + + * log + * [private files needed by TYPO3] + + * vendor - ddev composer req t3docs/site-package:"@dev" + * [All installed packages, including TYPO3 source] + * composer.json + * composer.lock .. _minimal-extension-siteset: @@ -108,7 +223,7 @@ 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/SitePackage/config.yaml + :caption: packages/my-site-package/Configuration/Sets/SitePackage/config.yaml You will learn more about site sets in chapter :ref:`site_set`. @@ -141,7 +256,7 @@ Create a file called :file:`setup.typoscript` containing basic TypoScript config in the folder of the site set you created in step :ref:`minimal-extension-siteset`: .. literalinclude:: _minimal.typoscript - :caption: packages/site-package/Configuration/Sets/SitePackage/setup.typoscript + :caption: packages/my-site-package/Configuration/Sets/SitePackage/setup.typoscript Clear all caches and preview the web page. @@ -158,7 +273,7 @@ Replace file :file:`setup.typoscript` of example :file:`minimal-extension-typoscript` with the following lines: .. literalinclude:: _pageview.typoscript - :caption: packages/site-package/Configuration/Sets/SitePackage/setup.typoscript + :caption: packages/my-site-package/Configuration/Sets/SitePackage/setup.typoscript :linenos: If you preview your page now you would get an error output like: @@ -183,17 +298,17 @@ By searching for the hash `bddd8a816bda3` in the log file you will find such an 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/ + The following paths were checked: /var/www/html/vendor/myvendor/my-site-package/Resources/Private/Templates/ 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/site-package/Resources/Private/Templates/Pages`. +:path:`packages/my-site-package/Resources/Private/Templates/Pages`. .. code-block:: html - :caption: packages/site-package/Resources/Private/Templates/Pages/Default.html + :caption: packages/my-site-package/Resources/Private/Templates/Pages/Default.html Hello Fluid World! @@ -226,7 +341,7 @@ a file called :file:`composer.json` was created for you: .. include:: /CodeSnippets/ExtensionConfiguration/ComposerJson.rst.txt At the top of the :file:`composer.json` file we see the Composer package name -`t3docs/site-package` (with a dash) and at the bottom we see the TYPO3 +`myvendor/my-site-package` (with a dash) and at the bottom we see the TYPO3 extension key in the extra section - :file:`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. @@ -235,7 +350,7 @@ When you reference files in your extension, the extension key is used, for example when setting your favicon in TypoScript: .. code-block:: typoscript - :caption: package/site_package/Configuration/Sets/SitePackage/setup.typoscript + :caption: package/my-site-package/Configuration/Sets/SitePackage/setup.typoscript page { shortcutIcon = EXT:site_package/Ressources/Public/Icons/favicon.ico