Person List 

Icon of the profile list
CType

academicpersons_list

Plugin

AcademicPersons, plugin List, actions ProfileController::listAction() and ProfileController::filterAction()

Set

fgtclb/academic-persons-list, or the aggregate set fgtclb/academic-persons

Templates

Templates/Profile/List.html, see Templates

The directory of a faculty, an institute or a whole institution: the profiles of one or more storage folders, optionally restricted to organisational units or function types, grouped by letter, paginated and filtered by the visitor. It is also the element for a short list of hand-picked profiles that should behave like a directory, with pagination and view modes.

The names link to the detail view of a profile on another page, which holds a Person Details element. A site that wants the list and the profile on one page uses Person List and Details instead. The partials that render the list are described in The list, its classes in The profile list, its URLs in Route enhancers.

Profile list with two filter selects and a filter button, the links Tiles and Table, and letter headings above profile tiles with name, position, function type, unit, e-mail and phone

A profile list with the visitor filters, the view mode switch and tiles grouped by the first letter of the last name.

Settings 

The tab Configuration holds the plugin options, in this order, and below them the Startingpoint.

PageTitle display format
Type
text, with a value picker
Default
empty

Has no effect in this element. The page title is set by the element that shows the profile, so set the format on the Person Details element of the detail page. The field exists here because the list shares its options with the list-and-detail element.

Detail Page
Type
page
Default
empty

The page the names link to. It has to hold a Person Details element. Empty uses the site setting plugin.tx_academicpersons.detailPid , and while that is 0 as well, the names link to the page of the list itself, with the arguments of the detail view. That only works when a Person Details element sits on the same page.

Group By (is given priority in sorting if active)
Type
select
Default
No grouping

First Letter of Last Name or First Letter of First Name puts a heading with the letter above each group of profiles, as in a telephone directory. The groups are always in ascending order, and Sort By orders the profiles within a group. The items come from the extension configuration demand.allowedGroupByValues.

The list is grouped page by page: in a paginated list, a group that continues on the next page gets its heading there again. A list of List of profiles is grouped in the order the selection meets the letters, so leave grouping off for a selection.

Sort By (sorting of activated grouping has priority)
Type
select
Default
No sorting

Last Name or First Name. No sorting lists the profiles in the order they were created. The items come from the extension configuration demand.allowedSortByValues. A list of List of profiles ignores the field and keeps the order of the selection.

Sort By Direction
Type
select
Default
Ascending

Ascending or Descending, for Sort By only. It does not reverse the groups.

Pagination
Type
checkbox
Default
off

Splits the list into pages of Results per Page profiles, with a page navigation below the list. While the visitor has selected a letter of the letter navigation, the list is not paginated and shows every profile of that letter.

Alphabetical Pagination
Type
checkbox
Default
off

Shows the letter navigation above the list: A-Z and one entry per letter, which narrows the list to the profiles whose last name starts with it. A letter without profiles in this list is shown disabled and is not a link. What the selected letter does is a site setting, see The selected letter of the letter navigation. The navigation is left out for a list of List of profiles.

Row of links A-Z and A to Z, some letters greyed out, above the group headings of the first letters

The letter navigation: letters without profiles are disabled.

Results per Page
Type
text
Default
empty

The number of profiles on one page. Fill it in whenever Pagination is on: a saved empty value replaces the site setting, and the element then fails with an exception instead of rendering the list.

Page navigation on the second page with the links first and previous and the page numbers 1 and 2

The page navigation of a paginated list, on its second page.

List of profiles
Type
records
Default
empty

Profiles picked by hand. The list then shows exactly these profiles, in the order they are picked. Sort By, the filters for visitors, the letter navigation and the restriction to Organisational Units and Function Types no longer decide which profiles are listed. Pagination, view modes, the contract options, Show hidden records and the language fallback still apply.

The Startingpoint applies as well: while it is set, a picked profile stored outside of it is not shown. For a selection that needs neither pagination nor a letter navigation, Selected Person’s Profiles is the simpler element.

View Mode Toggle
Type
checkbox
Default
off

Offers the visitor a switch between the allowed view modes above the list, when at least two are allowed. The active mode is marked as current, and the pagination and the letter navigation keep the chosen mode. Off, a mode the request asks for is ignored and View Mode Default renders.

Which modes exist is the site setting plugin.tx_academicpersons.viewMode.allowed.

View Mode Default
Type
select
Default
Tiles

The mode the list renders: Tiles, a grid of profile items, or Table, one row per profile with the columns of the site setting plugin.tx_academicpersons.table.columns. In a grouped list, every group is a table of its own. The stored value of the tiles is list, so an element saved before the field existed, or without it, renders the tiles. A default the site does not allow falls back to the tiles, or to the first allowed mode where the tiles are not allowed. A mode of a project is offered here through page TSconfig, see Adding a view mode.

Table with columns name, position, e-mail, phone and room for each letter group, below the view mode switch

The table view mode, one table per letter group, with the columns of the site setting plugin.tx_academicpersons.table.columns .

Fallback to default language for non translated profiles
Type
checkbox
Default
on

On a translated page, also lists the profiles that are not translated into its language, in the default language. Off, the fallback type of the site language decides, and a language with fallbackType: strict lists only the translated profiles. For a list of List of profiles on TYPO3 v13 see Important: Strict language fallback for selected profiles.

Show only selected Fields
Type
select, several values
Default
empty

The fields each profile item shows: the Image of the profile, and the Position, Function Type, Organisational Unit, Room, Office hours, Addresses, Email Addresses, Phone Numbers and Location / Campus of each shown contract, in the order of the right-hand list. The name is always shown. Empty shows the image and every contract field except the function type and the organisational unit, which appear only when they are selected.

The table view mode follows the selection: a contract column whose field is not selected, contracts.room for the column room, is left out. A listener of \FGTCLB\AcademicBase\Event\ModifyTcaSelectFieldItemsEvent can add items, which a template of the project then renders.

Organisational Units
Type
select, several values
Default
empty

Restricts the list to the profiles with a contract in one of the selected units, for the directory of one faculty or institute. A contract in a unit below a selected one does not count. Empty restricts nothing. The selected units are also the choices of the filter for visitors.

With Function Types selected as well, both have to match the same contract: a person who is a professor in one unit and a lecturer in another is not listed among the professors of the second one. Without Only contracts of the selected organisational units and function types, the restriction selects the profiles, and every contract of a listed profile is shown.

Function Types
Type
select, several values
Default
empty

The same restriction for function types, for a list of the professors or of the staff of a unit.

Visitors may filter by function type
Type
checkbox
Default
off

Shows a choice of function types above the list, see Filters for visitors.

Visitors may filter by organisational unit
Type
checkbox
Default
off

The same for organisational units.

Contracts per profile
Type
select
Default
All contracts

All contracts, or Only the first contract that the two options below leave, in the order the editor gave the contracts of the profile. See Which contracts a profile shows.

Only contracts of the selected organisational units and function types
Type
checkbox
Default
off

Leaves out the contracts of a listed profile in other units or with other function types than the list is restricted to. Without such a restriction it has no effect. See Which contracts a profile shows.

Only contracts valid today
Type
checkbox
Default
off

Leaves out the contracts that have ended or not started yet, and selects profiles only through a contract that is valid today. See Which contracts a profile shows and The page cache follows the validity.

Show hidden records
Type
checkbox
Default
off

Lists the profiles whose Visible switch is off as well, for an internal directory on a page restricted to a frontend user group. Switch it on in the detail element as well, or the names of hidden profiles lead to the error page. See Profiles that are not public.

Startingpoint
Type
pages
Default
empty

The folders the profiles are stored in. Their subfolders are not included, so select every folder. Empty lists the profiles of the whole installation, of every site.

Filters for visitors 

A visitor can narrow the list and list-and-detail elements to one function type or one organisational unit, where the element allows it. Two fields of the content element, Visitors may filter by function type and Visitors may filter by organisational unit, switch the filters on. Both are off by default, and a list that does not switch them on shows what it showed before:

Visitors may filter by function type
The list takes a function type from the request and shows only the profiles with a contract of that type.
Visitors may filter by organisational unit
The same for an organisational unit. The unit has to match exactly, a contract in a unit below it does not count.
Two selects, function type set to Professor and organisational unit, and a filter button above the filtered profiles

The filters for visitors, with a function type chosen.

With both filters set, the function type and the unit have to be on the same contract: a person who is a professor in one unit and a lecturer in another is not listed among the professors of the second one. A profile with several matching contracts is listed once, and the pagination and the letter navigation count only the profiles the filter leaves.

The options of a filter are the function types or units the element is restricted to in Function Types and Organisational Units, or all of them while it is restricted to none, ordered by name. A visitor can therefore never see more than the editor chose. The list ignores a value that is not one of the options: a number of a record that does not exist or is hidden, a record outside the restriction, anything that is not a whole number, and any value while the field is off. It then renders as if no filter had been given. A manual selection of profiles ignores both filters.

The request carries the uid of the record in the default language, as the demand arguments functionTypeFilter and organisationalUnitFilter of the plugin. The list renders a form above the profiles with one choice per filter, and its submission leads to the URL of the filtered list, see Filtered lists. The list template receives the options as filterOptions, see The options of the visitor filters. The page and letter links keep an active filter.

The filters select profiles, and do not change which contracts of a profile are shown. Only contracts of the selected organisational units and function types applies the restriction of the element, not the choice of the visitor. While Only contracts valid today is on, a filter finds a profile only through a contract valid today, see Which contracts a profile shows.

The card element shares the fields with the list and hides both.

Which contracts a profile shows 

A profile has one or more contracts, sorted by the editor. Every view shows all of them unless it is told otherwise.

The list and list-and-detail elements offer three fields in their plugin options, below the filters for visitors:

Contracts per profile
All contracts (the default), or only the first one.
Only contracts of the selected organisational units and function types
Leaves out the contracts of a profile in other units or with other function types than the element is restricted to. Without such a restriction the option has no effect. Without the option, the restriction selects the profiles and every contract of a selected profile is shown, as before.
Only contracts valid today
Leaves out the contracts that have ended or not started yet. While the element is restricted to organisational units or function types, or a visitor filters it, the option also decides which contracts select a profile: only one valid today does. A profile whose only matching contract has ended is not listed, rather than listed without that contract, and the pagination and the letter navigation count the same profiles. A list without such conditions selects nobody by a contract and still lists a profile whose contracts have all ended, without a contract.

The card and selected-profiles elements offer Contracts per profile and Only contracts valid today. They select their profiles by hand and apply no unit or function type restriction, so there is nothing for the contracts to match. The card hides the field in its form. A value stored while the element was a list stays in effect after a switch to the card, as a detail page stored while it was a list does.

The detail view, of the detail and the list-and-detail elements, is configured in Settings.yaml, once for the installation rather than per content element. Its two blocks rendered from the contracts take a key each for the same two choices, see The contracts of the position and contact blocks:

EXT:my_sitepackage/Configuration/AcademicPersons/Settings.yaml 
profile:
  details:
    position:
      onlyValid: true
    contact:
      contracts: first
Copied!

The selected-contracts element and the contacts element of EXT:academic_contacts4pages show the contract that was chosen, whatever the options say, even one that has ended.

The options apply in a fixed order: the unit and function type filter, then validity, then "first". "Only the first" is the first of the contracts left, in the editor's order of the profile's contracts, so a list restricted to one unit shows each profile's first contract in that unit.

Validity is a matter of days. A contract is valid from the first day of Valid from through the last day of Valid to. An empty date does not limit it on that side, and no setting changes that. "Today" is the date the page is rendered for, in the time zone of the installation. A date simulated in the frontend preview of a backend user counts.

The page cache follows the validity 

A cached page would keep showing a contract that ended yesterday until its cache entry expires. On TYPO3 v13 a page with profiles expires after 24 hours at the latest, whatever config.cache_period says, because every record Extbase loads limits the page to that. On TYPO3 v14 a page without config.cache_period is cached for a year. So while "only contracts valid today" applies, a page is cached no longer than until the next midnight on which a contract that passes the unit and function type filter ends, the day after its Valid to, or starts. While the option also decides which contracts select the profiles of a list, the same holds for every contract that meets the restriction and the visitor filters of the list, so a profile whose contract starts tomorrow is listed tomorrow, though nothing of it was rendered today. Those contracts are read from the storage pages of the list. The limit is set only on the cache entry of the page that rendered those contracts or the list, only when that date comes before the regular expiry, and never when no validity option applies.