Use Routing to rewrite URLs

This section will show you how you can rewrite the URLs for news using Routing Enhancers and Aspects. TYPO3 Explained has an capter Introduction to routing that you can read if you are not familiar with the concept yet. You will no longer need third party extensions like RealURL or CoolUri to rewrite and beautify your URLs.

How to rewrite URLs with news parameters

On setting up your page you should already have created a site configuration. You can do this in the backend module Site Managements > Sites.

Your site configuration will be stored in /config/sites/<your_identifier>/config.yaml. The following configurations have to be applied to this file.

Any URL parameters can be rewritten with the Routing Enhancers and Aspects. These are added manually in the config.yaml:

  1. Add a section routeEnhancers, if one does not already exist.
  2. Choose an unique identifier for your Routing Enhancer. It doesn’t have to match any extension key.
  3. type: For news, the Extbase Plugin Enhancer (Extbase) is used.
  4. extension: the extension key, converted to UpperCamelCase.
  5. plugin: the plugin name of news is just Pi1.
  6. After that you will configure individual routes and aspects depending on your use case.
/config/sites/<your_identifier>/config.yaml
1
2
3
4
5
6
routeEnhancers:
  News:
    type: Extbase
    extension: News
    plugin: Pi1
    # 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.

/config/sites/<your_identifier>/config.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
routeEnhancers:
  News:
    type: Extbase
    limitToPages:
      - 8
      - 10
      - 11
    extension: News
    plugin: Pi1
    # routes and aspects will follow here

Multiple routeEnhancers for news

If you use the news extension for different purposes on the same website (for example news and events), you may want different URL paths for them (for example /article/ and /event/). It is possible to configure more than one routing enhancer for the news plugin on the same website.

Use limitToPages to assign the appropriate configuration to the desired pages.

/config/sites/<your_identifier>/config.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
routeEnhancers:
  News:
    type: Extbase
    limitToPages:
      - 8
      - 10
      - 11
    extension: News
    plugin: Pi1
    # etc.
  NewsEvents:
    type: Extbase
    limitToPages:
      - 17
      - 18
    extension: News
    plugin: Pi1
    # 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 for
    example 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=
  1. URL of detail page with routes:
https://www.example.com/news/detail/5?cHash=
  1. 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:

/config/sites/<your_identifier>/config.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
routeEnhancers:
  News:
    type: Extbase
    extension: News
    plugin: Pi1
    routes:
      - routePath: '/{news-title}'
        _controller: 'News::detail'
        _arguments:
          news-title: news
    aspects:
      news-title:
        type: PersistedAliasMapper
        tableName: tx_news_domain_model_news
        routeFieldName: path_segment

Please note the placeholder {news-title}:

  1. First, you assign the value of the news parameter (tx_news_pi1[news]) in _arguments.
  2. Next, in routePath you add it to the existing route.
  3. Last, you use aspects to map the path_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, tags and the RSS/Atom feed)

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
/config/sites/<your_identifier>/config.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
routeEnhancers:
  News:
    type: Extbase
    extension: News
    plugin: Pi1
    routes:
      - routePath: '/'
        _controller: 'News::list'
      - routePath: '/page-{page}'
        _controller: 'News::list'
        _arguments:
          page: 'currentPage'
      - routePath: '/{news-title}'
        _controller: 'News::detail'
        _arguments:
          news-title: news
      - routePath: '/{category-name}'
        _controller: 'News::list'
        _arguments:
          category-name: overwriteDemand/categories
      - routePath: '/{tag-name}'
        _controller: 'News::list'
        _arguments:
          tag-name: overwriteDemand/tags
    defaultController: 'News::list'
    defaults:
      page: '0'
    aspects:
      news-title:
        type: PersistedAliasMapper
        tableName: tx_news_domain_model_news
        routeFieldName: path_segment
      page:
        type: StaticRangeMapper
        start: '1'
        end: '100'
      category-name:
        type: PersistedAliasMapper
        tableName: sys_category
        routeFieldName: slug
      tag-name:
        type: PersistedAliasMapper
        tableName: tx_news_domain_model_tag
        routeFieldName: slug
  PageTypeSuffix:
    type: PageType
    map:
      'feed.xml': 9818
      'calendar.ical': 9819

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
/config/sites/<your_identifier>/config.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
routeEnhancers:
  News:
    type: Extbase
    extension: News
    plugin: Pi1
    routes:
      - routePath: '/{page-label}-{page}'
        _controller: 'News::list'
        _arguments: {'page': 'currentPage'}
    defaultController: 'News::list'
    defaults:
      page: ''
    requirements:
      page: '\d+'
    aspects:
      page:
        type: StaticRangeMapper
        start: '1'
        end: '100'
      page-label:
        type: LocaleModifier
        default: 'page'
        localeMap:
          - locale: 'da_DK.*'
            value: 'side'
          - locale: 'de_DE.*'
            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
/config/sites/<your_identifier>/config.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
routeEnhancers:
  DateMenu:
    type: Extbase
    extension: News
    plugin: Pi1
    routes:
      # Pagination:
      - routePath: '/'
        _controller: 'News::list'
      - routePath: '/page-{page}'
        _controller: 'News::list'
        _arguments:
          page: 'currentPage'
        requirements:
          page: '\d+'
      - routePath: '/{news-title}'
        _controller: 'News::detail'
        _arguments:
          news-title: news
      # Date year:
      - routePath: '/{date-year}'
        _controller: 'News::list'
        _arguments:
          date-month: 'overwriteDemand/month'
          date-year: 'overwriteDemand/year'
          page: 'currentPage'
        requirements:
          date-year: '\d+'
      # Date year + pagination:
      - routePath: '/{date-year}/page-{page}'
        _controller: 'News::list'
        _arguments:
          date-year: 'overwriteDemand/year'
          page: 'currentPage'
        requirements:
          date-year: '\d+'
          page: '\d+'
      # Date year/month:
      - routePath: '/{date-year}/{date-month}'
        _controller: 'News::list'
        _arguments:
          date-month: 'overwriteDemand/month'
          date-year: 'overwriteDemand/year'
          page: 'currentPage'
        requirements:
          date-month: '\d+'
          date-year: '\d+'
       # Date year/month + pagination:
      - routePath: '/{date-year}/{date-month}/page-{page}'
        _controller: 'News::list'
        _arguments:
          date-month: 'overwriteDemand/month'
          date-year: 'overwriteDemand/year'
          page: 'currentPage'
        requirements:
          date-month: '\d+'
          date-year: '\d+'
          page: '\d+'
    defaultController: 'News::list'
    defaults:
      page: '0'
      date-month: ''
      date-year: ''
    aspects:
      news-title:
        type: PersistedAliasMapper
        tableName: tx_news_domain_model_news
        routeFieldName: path_segment
      page:
        type: StaticRangeMapper
        start: '1'
        end: '25'
      date-month:
        type: StaticValueMapper
        map:
          january: '01'
          february: '02'
          march: '03'
          april: '04'
          may: '05'
          june: '06'
          july: '07'
          august: '08'
          september: '09'
          october: '10'
          november: '11'
          december: '12'
      date-year:
        type: StaticRangeMapper
        start: '2000'
        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:

TypoScript setup
1
2
3
4
5
6
7
8
9
plugin.tx_news.settings.link {
    hrDate = 1
    hrDate {
        day = j
        // 'n' for 1 through 12. 'm' for 01 through 12.
        month = m
        year = Y
    }
}

You can configure each argument (day/month/year) separately by using the configuration of PHP function date.

Warning

Oops, an error occurred!
Possible range of all mappers is larger than 10000 items

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.