Item and list partials 

Which contracts an item renders 

Profile/Contract/Item.html renders the one contract a caller passes as contract - the selected contracts element and EXT:academic_contacts4pages do. Otherwise it renders the contracts the element's options select (see Which contracts a profile shows), through the ViewHelper <persons:contracts> . The detail view's Profile/PublicProfile/Position.html and Profile/PublicProfile/Contact.html use it with their block of Settings.yaml instead:

<html
    data-namespace-typo3-fluid="true"
    xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
    xmlns:persons="http://typo3.org/ns/FGTCLB/AcademicPersons/ViewHelpers"
>
<f:if condition="{contract}">
    <f:then>
        <p class="my-contract">{contract.position}</p>
    </f:then>
    <f:else>
        <f:for each="{persons:contracts(profile: profile, settings: settings)}" as="contract">
            <p class="my-contract">{contract.position}</p>
        </f:for>
    </f:else>
</f:if>
</html>

Keep the contract branch in a copy: without it, the selected contracts element and EXT:academic_contacts4pages would show the profile's contracts instead of the chosen one.

<f:for each="{persons:contracts(profile: profile, detailBlock: publicProfile.details.contact)}" as="contract">
    ...
</f:for>

settings are the plugin settings, detailBlock a block of publicProfile.details; a passed block wins. Without either, every contract is returned. The ViewHelper also limits the page cache lifetime while a validity option applies, which is why a template should call it rather than filter {profile.contracts} itself: a copy that loops over {profile.contracts} keeps working, and ignores the options.

The name of a function type 

Profile/Contract/FunctionTypeName.html renders the name of a function type for a profile's gender: the female name for ms, the male name for mr, and the general name otherwise or where the gendered name is empty. It takes the arguments functionType and gender. The position line of the detail view renders it, and so does Profile/Contract/Field.html for the field contracts.functionType of the fields to show. For that, Profile/Contract/Item.html hands the profile's gender to the field partial as gender. A project copy of Profile/Contract/Item.html that does not pass it shows the general name.

Two of them render text, not markup 

Profile/Item/Name.html and Profile/Item/DetailLink.html produce a value. The item hands it to Profile/Header.html or Profile/SectionHeader.html, which put it inside their heading element - and escape it there, once, on the way out.

An override of either therefore renders the profile values raw:

<html
    data-namespace-typo3-fluid="true"
    xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
>
<f:format.raw>{profile.lastName}</f:format.raw>, <f:format.raw>{profile.firstName}</f:format.raw>
</html>

Without <f:format.raw> the value is escaped twice, and a name such as O'Neill reaches the browser as the markup O'Neill, which a visitor reads as O'Neill. Markup written in one of these two partials arrives as literal text for the same reason - the heading element is what the header partials own.

Every other partial on this page renders markup and is written as any Fluid partial is.

Passing the detail page 

Profile/Item/DetailLink.html builds the address from plugin.tx_academicpersons.detailPid, or stays on the current page for the list-and-detail element, which shows the detail view itself. While plugin.tx_academicpersons.detailLink is none, it renders nothing for every other element and the name is shown as text, see Names without a detail link. An override of the partial follows that setting only when it checks it as well.

A template that renders an item without those plugin settings passes the page instead. A passed page wins over both branches, the list-and-detail one included, and links whatever plugin.tx_academicpersons.detailLink says:

<f:render
    partial="Profile/Item"
    arguments="{
        profile: profile,
        settings: settings,
        data: data,
        detailPid: 42
    }"
/>

What the navigation links carry 

The list action assigns activeListArguments: the choices of the visitor the list is shown with, as the plugin accepted them - the page while it is not the first, the letter while one is selected. A value of the request the plugin does not accept from a visitor is never part of it, nor is a value the content element sets, such as the sorting. The list template passes it to the letter navigation, and Profile/List/ItemList.html to the page navigation.

Both navigations build every link from it and change only what the link is responsible for, through the view helper persons:listArguments:

<html
    xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
    xmlns:persons="http://typo3.org/ns/FGTCLB/AcademicPersons/ViewHelpers"
    data-namespace-typo3-fluid="true"
>

<f:link.action
    arguments="{demand: '{persons:listArguments(arguments: activeListArguments, overrides: {currentPage: page})}'}"
>{page}</f:link.action>

<f:link.action
    arguments="{demand: '{persons:listArguments(arguments: activeListArguments, overrides: {alphabetFilter: letter}, remove: \'currentPage\')}'}"
>{letter}</f:link.action>

overrides sets values, remove drops the comma separated keys it names. A letter link and A-Z drop the page, so a new letter starts on the first page.

Besides page and letter, a visitor chooses the view mode, where the element offers the switch, and the filters, where the element offers them. A link carries each while it differs from the default. They reach activeListArguments like the other two, and both navigations carry them without an edit. A project copy of either partial, and a list template that does not pass activeListArguments on, keeps the links it has and drops the view mode and the filters on the next click, until it adopts the view helper as above.

The options of the visitor filters 

While the content element offers a filter for visitors, the list action assigns its options to filterOptions: filterOptions.functionTypes holds the function types, filterOptions.organisationalUnits the organisational units, each ordered by name in the language of the page. Each is known by its uid in the default language, which is the value a link carries. A filter the element does not offer has no key, and a manual selection gets no options at all. The active values are demand.functionTypeFilter and demand.organisationalUnitFilter, 0 for none.

The shipped list template renders them in Profile/List/Filter.html, above the letter navigation: one select per filter with options, "all" first, the active filter selected, and a submit button. The form posts to the filter action, which redirects to the URL of the filtered list, see Filtered lists. It keeps the view mode and the letter, and contains no JavaScript. The partial takes filterOptions, demand, activeListArguments and contentElementUid, which keeps the ids of a list and a list-and-detail element on one page apart. Two elements of the same plugin on one page share their arguments, as their page links do, so a submission is checked against the options of the element that renders first. A project copy of Profile/List.html that does not render the partial shows no form.

A project that prefers links to a form links a filtered list with the action link view helper, which adds the cHash the cached list needs, and keeps the other choices of the visitor:

<html
    xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
    xmlns:persons="http://typo3.org/ns/FGTCLB/AcademicPersons/ViewHelpers"
    data-namespace-typo3-fluid="true"
>

<f:for each="{filterOptions.functionTypes}" as="functionType">
    <f:link.action
        arguments="{demand: '{persons:listArguments(arguments: activeListArguments, overrides: {functionTypeFilter: functionType.uid}, remove: \'currentPage\')}'}"
    >{functionType.functionName}</f:link.action>
</f:for>

Profile/List/Items.html, the grid the view mode list renders, carries the Bootstrap row and column classes, so overriding it changes the grid of all four elements of this extension at once. It takes either profiles or contracts: the selected contracts element passes the latter, because it shows one item per selected contract, and each of those items renders that one contract rather than every contract of its profile.

Profile/List/EmptyState.html is rendered by all four as well. The selected contracts element passes the label about contracts to it through its key argument; every other caller takes the default.

The grid is an ace-itemlist and the empty state an ace-empty in all four elements. What tells the elements apart is their outermost element, academic-persons-list, academic-persons-card, academic-persons-profiles or academic-persons-contracts.

The result count is an empty hook 

Profile/List/ResultCount.html renders nothing on purpose - printing a number by default would change every list that exists. It receives the number of profiles rendered below it as count, the number the list found as total - the same one unless the list paginates - those profiles as profiles, and the paginator of a paginated list for its page number and page count:

<html
    data-namespace-typo3-fluid="true"
    xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
>
<p class="ace-count">{count} of {total}</p>
</html>

total is counted in ItemList.html rather than read from the paginator on purpose: getTotalAmountOfItems() is protected on every core version this extension supports, so Fluid cannot reach it and {paginator.totalAmountOfItems} renders an empty string.

Adding a view mode 

A view mode of your own needs no template override. Taking the mode contact:

1. Provide the partial Profile/ViewMode/Contact.html in a partial path of the plugin, such as that of your site package.
2. Allow the mode: the site setting plugin.tx_academicpersons.viewMode.allowed becomes list,table,contact, see View modes.

3. Offer it to the editor as an item of View Mode Default, in page TSconfig, for each element that shall have it:

   EXT:my_sitepackage/Configuration/page.tsconfig

   TCEFORM.tt_content.pi_flexform {
     academicpersons_list.sDEF.settings\.viewMode\.default.addItems.contact = Contact cards
     academicpersons_listanddetail.sDEF.settings\.viewMode\.default.addItems.contact = Contact cards
   }

   Copied!

The switch offers the mode as soon as it is allowed; label it with list.viewMode.contact in a language override of this extension. A mode that is allowed without a partial fails with Fluid's error for a missing partial. Its links carry it as a query argument until it is added to the route enhancer, see a view mode of your own in the URL.

To add a column to the table, override Profile/ViewMode/Table/Cell.html, render your column there and keep the shipped ones; a column the partial does not know renders an empty cell. Its header is the label list.table.<column>, or the column's name without one.