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.

Neither variable carries a default, on purpose: a link that uses the default sorting generates /title/asc, not the plain page URL. The plain page URL is where the sorting configured in the content element applies, so a default would turn a link asking for the title, ascending, into a link to whatever the element is configured with. The same holds for an enhancer a site writes for this plugin itself. A path with the field alone, such as /last-updated, does not resolve.

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 (line breaks added, and the brackets not encoded, for reading):

/programs?tx_academicprograms_programlist[action]=list
    &tx_academicprograms_programlist[controller]=Program
    &tx_academicprograms_programlist[demand][sortingDirection]=desc
    &tx_academicprograms_programlist[demand][sortingField]=lastUpdated
    &cHash=…

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 to a URL without any sorting. That URL does not enter the route, so its requests are not enhanced — after a submit the address bar shows the page URL with the plugin's action, controller and cache hash in the query string. The enhancer takes effect for links that are built with the sorting 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, so every one of the six combinations they can spell is reachable — and SortingOptions defines exactly those six, so each path the enhancer resolves is an ordering the plugin really renders. Until the reversed page sorting was added, /sorting/desc resolved to an option that did not exist and was silently dropped.