..  index:: Configuration; Route enhancers
..  _configuration-route-enhancers:

===============
Route enhancers
===============

This extension ships three ready made route enhancers below
:file:`Configuration/Routes/`. TYPO3 does not read those files on its own —
they are fragments that have to be imported from the configuration of the site
which shows the plugins.

Each file covers exactly one plugin, so which of them you import follows from
which plugins the site actually uses.

What the files enhance
----------------------

:file:`Detail.yaml`
    Enhancer :yaml:`ProfileDetailPlugin` for the plugin :yaml:`Detail`,
    argument namespace :php:`tx_academicpersons_detail`. One route,
    :yaml:`/{profile_name}`, for the :php:`detail` action, mapping the argument
    :yaml:`profile`. The path segment is resolved by a
    :yaml:`PersistedAliasMapper` on the table
    :sql:`tx_academicpersons_domain_model_profile` over the field
    :sql:`slug`.

:file:`List.yaml`
    Enhancer :yaml:`ProfileListPlugin` for the plugin :yaml:`List`, argument
    namespace :php:`tx_academicpersons_list`. Two routes for the :php:`list`
    action: :yaml:`{localized_page}-{page}` for :yaml:`demand/currentPage` and
    :yaml:`/{letter}` for :yaml:`demand/alphabetFilter`. The page number is
    limited to a :yaml:`StaticRangeMapper` from 1 to 1000, the letter to a
    :yaml:`StaticRangeMapper` from ``a`` to ``z``, and the word in front of
    the page number is translated by a :yaml:`LocaleModifier` — ``page`` by
    default, ``seite`` for German.

:file:`ListAndDetail.yaml`
    Enhancer :yaml:`ProfileListAndDetailPlugin` for the plugin
    :yaml:`ListAndDetail`, argument namespace
    :php:`tx_academicpersons_listanddetail`. It is the union of the two above:
    the detail route, the pagination route and the letter route, with the same
    aspects, because that plugin renders both the list and the detail view.

Which file to import
--------------------

The three enhancers are bound to three different plugins, so they never collide
and importing more than one is normal:

*   A site that puts the :guilabel:`List` plugin on one page and the
    :guilabel:`Detail` plugin on another — the usual setup, where the list
    links to the detail page through the plugin setting
    :typoscript:`detailPid` — imports :file:`List.yaml` **and**
    :file:`Detail.yaml`.
*   A site that puts the single :guilabel:`ListAndDetail` plugin on one page
    imports :file:`ListAndDetail.yaml` only.
*   A site that uses both variants imports all three.

The remaining plugins of this extension — :yaml:`SelectedProfiles`,
:yaml:`SelectedContracts` and :yaml:`Card` — take no frontend arguments, so no
enhancer is shipped for them.

Importing into a site configuration
-----------------------------------

Add the resources to the :yaml:`imports` of the site:

..  code-block:: yaml
    :caption: config/sites/my_site/config.yaml

    imports:
      - resource: 'EXT:academic_persons/Configuration/Routes/List.yaml'
      - resource: 'EXT:academic_persons/Configuration/Routes/Detail.yaml'
      - resource: 'EXT:academic_persons/Configuration/Routes/ListAndDetail.yaml'

What the URLs look like
-----------------------

Assuming the list plugin sits on a page with the slug :file:`/persons` and the
detail plugin on :file:`/persons/profile`, the URLs change as follows.

..  code-block:: text
    :caption: Without the enhancers

    /persons?tx_academicpersons_list%5Bdemand%5D%5BcurrentPage%5D=2
    /persons?tx_academicpersons_list%5Bdemand%5D%5BalphabetFilter%5D=m
    /persons/profile?tx_academicpersons_detail%5Bprofile%5D=42

..  code-block:: text
    :caption: With the enhancers imported

    /persons/page-2
    /persons/m
    /persons/profile/jane-doe

Caveats
-------

*   The detail route needs a slug. :yaml:`PersistedAliasMapper` resolves the
    path segment against the :sql:`slug` field of the profile record, so a
    profile whose slug is empty cannot be reached through the enhanced URL. The
    slug is generated by the TCA :php:`slug` field, which means it is filled
    when the record is saved in the backend. Profiles created by
    :bash:`academicpersons:createprofiles` are persisted through the Extbase
    persistence manager and therefore never pass the :php:`DataHandler`, so
    those records — and records that predate the field — start out with an
    empty slug and have to be saved once in the backend before the enhanced
    URL resolves.
*   The two list routes are alternatives, not a combination. A link that
    carries a page number *and* a letter matches the pagination route, and the
    letter stays behind as a query argument —
    :file:`/persons/page-2?tx_academicpersons_list[demand][alphabetFilter]=m`.
*   Only the mapped value ranges are put into the path. A page number above
    1000, and the empty filter value that the :guilabel:`A-Z` reset link of the
    alphabet pagination submits, are outside the mapped ranges, so those links
    keep their query argument.
*   The :yaml:`localeMap` of the :yaml:`LocaleModifier` is matched against the
    locale of the site language, with the underscores replaced by hyphens and
    anchored at the start. The shipped map lists :yaml:`en_EN.*` and
    :yaml:`de_DE.*`, which means a German language configured as :yaml:`de-DE`
    is translated to ``seite`` while a plain :yaml:`de` is not. Adjust the map
    to the locales your site actually uses.
*   Unlike the program list of :guilabel:`academic_programs`, the pagination
    and the alphabet filter of this extension are rendered as links, not as a
    form, so their own requests do carry the arguments in the URL and are
    enhanced.