Route enhancers

This extension ships one ready made route enhancer in Configuration/Yaml/Routes.yaml. TYPO3 does not read that file on its own — it is a fragment that has to be imported from the configuration of the site which shows the plugin.

What the file enhances

The file declares a single enhancer of type Extbase named AcademicPrograms, bound to the plugin ProgramList of the extension AcademicPrograms. That pair is what determines the argument namespace the enhancer works on — tx_academicprograms_programlist.

It registers one route for the list action of \FGTCLB\AcademicPrograms\Controller\ProgramController:

EXT:academic_programs/Configuration/Yaml/Routes.yaml

routes:
  - routePath: '/{sorting_field}/{sorting_direction}'
    _controller: 'Program::list'
    _arguments:
      sorting_field: demand/sortingField
      sorting_direction: demand/sortingDirection

Both path variables are mapped by a StaticValueMapper, so only the values below ever appear in a URL, and anything else is rejected:

sorting_field — the segment title selects the demand value title, last-updated selects lastUpdated and sorting selects sorting.
sorting_direction — asc and desc.

Those are the values of \FGTCLB\AcademicPrograms\Enumeration\SortingOptions, which is also what the sorting select field of the plugin offers.

Both variables carry a default — title and asc. They are the trailing segments of the route path, so a link that uses the default sorting generates the plain page URL rather than /title/asc.

Importing it into a site configuration

Add the resource to the imports of the site that contains the page with the program list plugin:

config/sites/my_site/config.yaml

imports:
  - resource: 'EXT:academic_programs/Configuration/Yaml/Routes.yaml'

The import is merged into the site configuration, so an installation that already defines other enhancers keeps them as long as no key is named AcademicPrograms twice. That is a statement about the merge and about nothing else: distinct keys keep the entries, they do not keep two enhancers from producing routes which match the same URL.

Limiting the enhancer to its page

TYPO3 offers every enhancer declared in a site configuration to every page of that site unless the enhancer says otherwise, and it takes the first candidate route whose path matches and whose aspects resolve. The order the candidates are tried in is the order of the imports.

The route of this extension is comparatively hard to collide with, and that is owed to its mappers rather than to its key: both path variables are handled by a StaticValueMapper, so a candidate is only accepted when the segments are one of the three sorting fields followed by asc or desc. Anything else is rejected and the next enhancer gets its turn. A route variable that is mapped less narrowly — one whose aspect comes without an explicit requirements entry compiles to .+ and crosses slashes — has no such protection, and even here a second extension mapping values of the same spelling is enough to make the two compete.

limitToPages settles it by naming the pages the enhancer applies to:

config/sites/my_site/config.yaml

imports:
  - resource: 'EXT:academic_programs/Configuration/Yaml/Routes.yaml'

routeEnhancers:
  AcademicPrograms:
    limitToPages: [23]

The uid is the one of the page carrying the list plugin, and it is the uid of the default language: matching derives the page as l10n_parent ?: uid, so a single entry covers every translation of that page. Plain page uids work on every TYPO3 version this extension supports.

In academic_persons the same mechanism is not a precaution but a requirement — that extension ships three enhancers whose routes overlap each other by construction. See its route enhancer documentation.

What the URLs look like

Assuming the plugin sits on a page with the slug /programs, a link that sorts by the last update, descending, is built without the enhancer as:

/programs?tx_academicprograms_programlist%5Bdemand%5D%5BsortingField%5D=lastUpdated&tx_academicprograms_programlist%5Bdemand%5D%5BsortingDirection%5D=desc

and with the enhancer imported as:

/programs/last-updated/desc

Caveats

Warning

The sorting and filter form shipped with the list plugin submits by POST. Its own requests therefore carry no arguments in the URL at all and are not enhanced — the address bar keeps showing the plain page URL after a submit. The enhancer takes effect for links that are built with the arguments as GET parameters, for example a f:link.action in an own template override or a hand written link.

Two further points are worth knowing:

The enhancer covers the list plugin only. The detail plugin (ProgramDetails) takes no arguments — it renders the program of the page it sits on — so there is nothing to map into a path for it.
The two mappers are independent, which makes six combinations reachable while SortingOptions only defines five. /sorting/desc resolves although the plugin never offers it as an option.