User's round trip¶
When a user wants to find out more about a TYPO3 extension, Composer package or a standalone manual, they should be provided with information about every aspect of the project including its rendered documentation, code repository and the Packagist and TYPO3 Extension Repository (TER) pages.
It is recommended that you set up a navigation structure that signposts every part of your project so that users can quickly install, learn and potentially contribute to your project. This can be achieved by using the native configuration settings.
Table of Contents:
Project aspects¶
Create the round trip by cross-referencing between all aspects of a project as follows.
Documentation¶
Guide the user from the documentation to the other aspects by setting these Sphinx theme configuration properties at Settings: Documentation/Settings.cfg:
project_home = <typo3-extension-repository>
project_repository = <vcs-repository>
project_issues = <vcs-repository-issues>
for example for the News System extension:
project_home = https://extensions.typo3.org/extension/news/
project_repository = https://github.com/georgringer/news
project_issues = https://github.com/georgringer/news/issues
and find the links to the other aspects displayed in the footer of the rendered documentation (see News System example).
For a Composer package, replace the TER URL with the Packagist URL. For a standalone manual, replace the TER URL with the documentation URL.
The Packagist URL is linked indirectly from the TER page and is therefore not specified in this configuration file. The issues URL is specified, but not considered part of the round trip, as it usually does not provide a way to link to other aspects.
VCS repository¶
Guide the user from the VCS repository page to the other aspects by offering a table in the README file:
| | URL |
|------------------|------------------------------------------------|
| **Repository:** | <vcs-repository> |
| **Read online:** | <documentation> |
| **TER:** | <typo3-extension-repository> |
for example for the Mask extension:
| | URL |
|------------------|------------------------------------------------|
| **Repository:** | https://github.com/Gernott/mask |
| **Read online:** | https://docs.typo3.org/p/mask/mask/main/en-us/ |
| **TER:** | https://extensions.typo3.org/extension/mask |
and find the README file usually displayed by the VCS host below the file list of the repository (see Mask example).
For a Composer package, replace the TER URL with the Packagist URL and label it "Packagist:". For a standalone manual, remove the TER entry.
The Packagist URL is linked indirectly from the TER page and is therefore not included in this configuration file.
Packagist¶
Guide the user from the Packagist page to the other aspects by setting these
composer.json configuration values:
"homepage": "<typo3-extension-repository>",
"support": {
"docs": "<documentation>",
"issues": "<vcs-repository-issues>",
"source": "<vcs-repository>"
}
for example for the Address List extension:
"homepage": "https://extensions.typo3.org/extension/tt_address",
"support": {
"docs": "https://docs.typo3.org/p/friendsoftypo3/tt-address/main/en-us/",
"issues": "https://github.com/FriendsOfTYPO3/tt_address/issues",
"source": "https://github.com/FriendsOfTYPO3/tt_address"
}
and find the links to the other aspects shown in the right column of the Packagist page (see Address List example).
For a Composer package, replace the TER URL with the Packagist URL.
The issues URL is specified, but not considered part of the round trip, as it usually does not provide a way to link to other aspects.
TYPO3 Extension Repository¶
Guide the user from the TER page to the other aspects by setting these configuration values on the extension management page:
Published on Packagist: check
Composer name of extension:
<package-name>Link to issue tracker:
<vcs-repository-issues>Link to repository:
<vcs-repository>
for example for the Static File Cache extension:
Published on Packagist: check
Composer name of extension: lochmueller/staticfilecache
Link to issue tracker: https://github.com/lochmueller/staticfilecache/issues
Link to repository: https://github.com/lochmueller/staticfilecache
and find the links to the other aspects presented in the right column of the TER page (see Static File Cache example).
The documentation URL is automatically resolved when the documentation is published on docs.typo3.org. The issues URL is specified, but not considered part of the round trip, as it usually does not provide a way to link to other aspects.
Project types¶
It depends on your project type whether all aspects can be configured or only a subset.
TYPO3 extension¶
Guide the user to all four aspects of the TYPO3 extension, which is usually distributed on both TER and Packagist, by configuring:
For example, look at the Apache Solr extension and try navigating all four aspects by simply clicking on a redirect link on each page - starting at the Apache Solr TER page.
Composer package¶
A Composer package that is not a TYPO3 extension is usually distributed only on Packagist. Therefore, guide the user to three aspects of the package by configuring:
For example, examine the TYPO3 Console package and try navigating through its three aspects by just clicking on a redirecting link on each page - starting at the TYPO3 Console Packagist page.
Standalone manual¶
A standalone manual, i.e. a tutorial, guide or reference, is usually not provided in a store. Therefore, guide the user to two aspects of the manual by configuring:
For example, take a look at the Getting Started tutorial and try navigating between the two aspects by simply clicking on a redirecting link on each page - starting at the Getting Started documentation.