Routing in TYPO3 9¶
This section will show you how you can rewrite the URLs for news using Routing Enhancers and Aspects.
Please keep in mind that these features are only available in TYPO3 9 LTS and above!
About routing in TYPO3¶
Since version 9.5, TYPO3 supports speaking URLs out of the box. You will no longer need third party extensions like RealURL or CoolUri to rewrite and beautify your URLs. And in fact, at least RealURL will not be updated for newer TYPO3 versions!
First of all, you will need to create a Site Configuration. You can do this in the backend module "SITE MANAGEMENT > Sites". Once saved, TYPO3 will automatically rewrite your pages with the new routing features.
Your Site Configuration will be stored in /typo3conf/sites/<your_identifier>/config.yaml
.
Note
For more information about the new Site Handling in TYPO3 v9 please refer to the official documentation: https://docs.typo3.org/typo3cms/CoreApiReference/ApiOverview/SiteHandling/Index.html
How to rewrite URLs with news parameters¶
Any URL parameters can be rewritten with the aforementioned Routing Enhancers and Aspects.
These are added manually in the config.yaml
:
Add a section
routeEnhancers
, if one does not already exist.Choose an unique identifier for your Routing Enhancer. It doesn't have to match any extension key.
type
: For news, the Extbase Plugin Enhancer (Extbase
) is used.extension
: the extension key, converted toUpperCamelCase
.plugin
: the plugin name of news is just Pi1.After that you will configure individual routes and aspects depending on your use case.
1routeEnhancers:
2 News:
3 type: Extbase
4 extension: News
5 plugin: Pi1
6 # routes and aspects will follow here
Tip
If your routing doesn't work as expected, check the indentation of your configuration blocks. Proper indentation is crucial in YAML.
Using limitToPages¶
It is recommended to limit routeEnhancers
to the pages where they are needed.
This will speed up performance for building page routes of all other pages.
1routeEnhancers:
2 News:
3 type: Extbase
4 limitToPages:
5 - 8
6 - 10
7 - 11
8 extension: News
9 plugin: Pi1
10 # routes and aspects will follow here
Multiple routeEnhancers for news¶
If you use the news extension for different purposes on the same website (e.g. news and events), you may want different URL paths for them (e.g. /article/ and /event/). It's possible to configure more than one routing enhancer for the news plugin on the same website.
Use limitToPages
to assign the appropiate configuration to the desired pages.
1routeEnhancers:
2 News:
3 type: Extbase
4 limitToPages:
5 - 8
6 - 10
7 - 11
8 extension: News
9 plugin: Pi1
10 # etc.
11 NewsEvents:
12 type: Extbase
13 limitToPages:
14 - 17
15 - 18
16 extension: News
17 plugin: Pi1
18 # etc.
About routes and aspects¶
In a nutshell:
routes
will extend an existing route (means: your domain and page path) with arguments from GET parameters, like the following controller/action pair of the news detail view.
aspects
can be used to modify these arguments. You could e.g. map the title (or better: the optimized path segment) of the current news. Different types of Mappers and Modifiers are available, depending on the case.
1. URL of detail page without routing:
https://www.example.com/news/detail?tx_news_pi1[action]=detail&tx_news_pi1[controller]=News&tx_news_pi1[news]=5&cHash=
2. URL of detail page with routes:
https://www.example.com/news/detail/5?cHash=
3. URL of detail page with routes and aspects:
https://www.example.com/news/detail/title-of-news-article
The following example will only provide routing for the detail view:
1routeEnhancers:
2 News:
3 type: Extbase
4 extension: News
5 plugin: Pi1
6 routes:
7 - routePath: '/{news-title}'
8 _controller: 'News::detail'
9 _arguments:
10 news-title: news
11 aspects:
12 news-title:
13 type: PersistedAliasMapper
14 tableName: tx_news_domain_model_news
15 routeFieldName: path_segment
Please note the placeholder {news-title}
:
First, you assign the value of the news parameter (
tx_news_pi1[news]
) in_arguments
.Next, in
routePath
you add it to the existing route.Last, you use
aspects
to map thepath_segment
of the given argument.
Both routes and aspects are only available within the current Routing Enhancer.
The names of placeholders are freely selectable.
Common routeEnhancer configurations¶
Basic setup (including categories and tags)¶
Prerequisites:
The plugins for list view and detail view are on separate pages. If you use the category menu or tag list plugins to filter news records, their titles (slugs) are used.
Result:
Detail view:
https://www.example.com/news/detail/the-news-title
Pagination:
https://www.example.com/news/page-2
Category filter:
https://www.example.com/news/my-category
Tag filter:
https://www.example.com/news/my-tag
1routeEnhancers:
2 News:
3 type: Extbase
4 extension: News
5 plugin: Pi1
6 routes:
7 - routePath: '/page-{page}'
8 _controller: 'News::list'
9 _arguments:
10 page: '@widget_0/currentPage'
11 - routePath: '/{news-title}'
12 _controller: 'News::detail'
13 _arguments:
14 news-title: news
15 - routePath: '/{category-name}'
16 _controller: 'News::list'
17 _arguments:
18 category-name: overwriteDemand/categories
19 - routePath: '/{tag-name}'
20 _controller: 'News::list'
21 _arguments:
22 tag-name: overwriteDemand/tags
23 defaultController: 'News::list'
24 defaults:
25 page: '0'
26 aspects:
27 news-title:
28 type: PersistedAliasMapper
29 tableName: tx_news_domain_model_news
30 routeFieldName: path_segment
31 page:
32 type: StaticRangeMapper
33 start: '1'
34 end: '100'
35 category-name:
36 type: PersistedAliasMapper
37 tableName: sys_category
38 routeFieldName: slug
39 tag-name:
40 type: PersistedAliasMapper
41 tableName: tx_news_domain_model_tag
42 routeFieldName: slug
Warning
The slug
fields for categories and tags are only available when using news 7.1.0 or higher.
Localized pagination¶
Prerequisites:
The website provides several frontend languages.
Result:
English:
https://www.example.com/news/page-2
Danish:
https://www.example.com/da/news/side-2
German:
https://www.example.com/de/news/seite-2
1routeEnhancers:
2 News:
3 type: Extbase
4 extension: News
5 plugin: Pi1
6 routes:
7 - routePath: '/{page-label}-{page}'
8 _controller: 'News::list'
9 _arguments: {'page': '@widget_0/currentPage'}
10 defaultController: 'News::list'
11 defaults:
12 page: ''
13 requirements:
14 page: '\d+'
15 aspects:
16 page:
17 type: StaticRangeMapper
18 start: '1'
19 end: '100'
20 page-label:
21 type: LocaleModifier
22 default: 'page'
23 localeMap:
24 - locale: 'da_.*'
25 value: 'side'
26 - locale: 'de_.*'
27 value: 'seite'
Explanation:
The LocaleModifier
aspect type will set a default value for the english language.
You're then able to add as many localeMap
configurations as you need for the page translations of your website.
The value of locale
refers to the value in your site configuration.
Human readable dates¶
Prerequisites:
For list view with a date menu plugin, to filter by date. Also includes configuration for the pagination.
Result:
https://www.example.com/news/2018/march
https://www.example.com/news/2018/march/page-2
1routeEnhancers:
2 DateMenu:
3 type: Extbase
4 extension: News
5 plugin: Pi1
6 routes:
7 # Pagination:
8 - routePath: '/page-{page}'
9 _controller: 'News::list'
10 _arguments:
11 page: '@widget_0/currentPage'
12 requirements:
13 page: '\d+'
14 - routePath: '/{news-title}'
15 _controller: 'News::detail'
16 _arguments:
17 news-title: news
18 # Date year:
19 - routePath: '/{date-year}'
20 _controller: 'News::list'
21 _arguments:
22 date-month: 'overwriteDemand/month'
23 date-year: 'overwriteDemand/year'
24 page: '@widget_0/currentPage'
25 requirements:
26 date-year: '\d+'
27 # Date year + pagination:
28 - routePath: '/{date-year}/page-{page}'
29 _controller: 'News::list'
30 _arguments:
31 date-year: 'overwriteDemand/year'
32 page: '@widget_0/currentPage'
33 requirements:
34 date-year: '\d+'
35 page: '\d+'
36 # Date year/month:
37 - routePath: '/{date-year}/{date-month}'
38 _controller: 'News::list'
39 _arguments:
40 date-month: 'overwriteDemand/month'
41 date-year: 'overwriteDemand/year'
42 page: '@widget_0/currentPage'
43 requirements:
44 date-month: '\d+'
45 date-year: '\d+'
46 # Date year/month + pagination:
47 - routePath: '/{date-year}/{date-month}/page-{page}'
48 _controller: 'News::list'
49 _arguments:
50 date-month: 'overwriteDemand/month'
51 date-year: 'overwriteDemand/year'
52 page: '@widget_0/currentPage'
53 requirements:
54 date-month: '\d+'
55 date-year: '\d+'
56 page: '\d+'
57 defaultController: 'News::list'
58 defaults:
59 page: '0'
60 date-month: ''
61 date-year: ''
62 aspects:
63 news-title:
64 type: PersistedAliasMapper
65 tableName: tx_news_domain_model_news
66 routeFieldName: path_segment
67 page:
68 type: StaticRangeMapper
69 start: '1'
70 end: '25'
71 date-month:
72 type: StaticValueMapper
73 map:
74 january: '01'
75 february: '02'
76 march: '03'
77 april: '04'
78 may: '05'
79 june: '06'
80 july: '07'
81 august: '08'
82 september: '09'
83 october: '10'
84 november: '11'
85 december: '12'
86 date-year:
87 type: StaticRangeMapper
88 start: '2000'
89 end: '2030'
Explanation:
You will need a new routePath
for every possible combination of arguments (pagination, month with/without pagination, ...).
Potential errors:
If you want 2018/march
but get 2018/3
instead, compare your StaticValueMapper
for months with your date arguments.
Are you using different date formats (with/without leading zeros)?
You can either remove the leading zero in your aspects
or adapt the TypoScript setting:
1plugin.tx_news.settings.link {
2 hrDate = 1
3 hrDate {
4 day = j
5 // 'n' for 1 through 12. 'm' for 01 through 12.
6 month = m
7 year = Y
8 }
9}
You can configure each argument (day/month/year) separately by using the configuration of PHP function date (see http://www.php.net/date).
Warning
Using the StaticRangeMapper
is strictly limited to 1000 items per a single range
and 10000 items per routing enhancer.
That means you'll have to multiply all possible combinations in a routing enhancer, for example:
12 months × 30 years (2000-2030) × 25 pages (pagination) = 9000 possible items
If you exceed this limit, you'll either have to build a custom and more specific mapper,
or reduce the range in one of your StaticRangeMapper
.