Skip to content

Move Extension installation in minimal example #262

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
jonirouAtTalan wants to merge 1 commit into from
Closed

Move Extension installation in minimal example #262

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 0 additions & 123 deletions Documentation/ExtensionInstallation/Index.rst
View file
Open in desktop

This file was deleted.

151 changes: 133 additions & 18 deletions Documentation/MinimalExample/Index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]:
Expand All @@ -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 <extension-installation>`.
Expand All @@ -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 <t3sitepackage: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 <t3start:installation-ddev-tutorial>`

.. 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] <t3start:installation-ddev-tutorial>`

* config

* sites

* :ref:`[site identifier] <typo3-backend-site>`

* 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:
Expand All @@ -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`.
Expand Down Expand Up @@ -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.

Expand All @@ -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:
Expand All @@ -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!

Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand Down
Loading