Upgrading from 2.3 to 2.4

Version 2.4 delivers the configuration of academic_partners per component and hides its content elements until a site enables them. It also registers the static template under this extension, where 2.3 registered it under academic_programs, gives the partnerships of a role a sort column of their own and keeps the map data of translated partner pages in step with the default language. Work through the sections in order. Skip a step that does not apply to the installation.

Before you start

Version 2.4 runs on TYPO3 12.4 from 12.4.22 on and on TYPO3 13.4, with PHP 8.1 or later. That is the same as for 2.3, so the TYPO3 core does not have to change for this upgrade.

academic_partners 2.4 needs these packages. Upgrade them first or in the same deployment, in this order:

fgtclb/environment-state-manager 1.x, new in 2.4, which academic_base 2.4 requires. Composer installs it on its own. A classic installation installs environment_state_manager before it activates academic_base 2.4.
fgtclb/academic-base 2.4, the same release as this extension.
fgtclb/category-types 2.4, the same release as this extension.

Update the package

composer require -W \
    'fgtclb/academic-base':'~2.4.0' \
    'fgtclb/category-types':'~2.4.0' \
    'fgtclb/academic-partners':'~2.4.0'

A project that requires branch 2 as 2.x-dev keeps an inline alias such as 2.x-dev as 2.4.x-dev working, see Important: The development branch installs as 2.4.x-dev.

On a classic installation, install environment_state_manager 1.x from the TER in Admin Tools > Extensions first, then update academic_base, category_types and academic_partners there, in this order. Run the commands of this page with typo3/sysext/core/bin/typo3 instead of vendor/bin/typo3.

vendor/bin/typo3 cache:flush

Update the database

Compare the database schema in Admin Tools > Maintenance > Analyze Database Structure, or on the command line:

vendor/bin/typo3 extension:setup

The command creates and changes tables and columns and drops nothing. For this extension it adds one column and changes one:

Column	Change
`tx_academicpartners_domain_model_partnership.role_sorting`	Added. The position of a partnership in the list of its role, which the first wizard below fills. See Important: A partner role sorts its partnerships on its own.
`pages.link`	Changed from `text NOT NULL DEFAULT ''` to `text DEFAULT NULL`. No data is converted. On TYPO3 12 with MySQL this makes it possible to create pages again, see Important: The link column of pages is nullable now.

Run the upgrade wizards

Both wizards are new in 2.4. They need the columns of the database compare and do not depend on each other. Run them in this order, in Admin Tools > Upgrade > Upgrade Wizard or on the command line:

academicPartners_seedPartnershipRoleSorting, Seed the partnership sort order of academic partner roles. It fills role_sorting with the order the role forms show today, the current sorting of each partnership with its uid settling ties. It only appends what has no position yet, so a second run changes nothing an editor arranged. Until it has run, a role form lists its partnerships in arbitrary order. See Important: A partner role sorts its partnerships on its own.
```
vendor/bin/typo3 upgrade:run academicPartners_seedPartnershipRoleSorting
```
Copied!
academicPartners_synchronizePartnerTranslations, Synchronize academic partner pages with their translations. It copies the coordinates and the switch Show on map of every partner page onto its translations, once. A translation made before the page was geocoded carries an empty coordinate, and one made while the partner was hidden from the map keeps it off the map in its language. Translations whose fields an editor detached, deleted pages and workspace versions are left alone. See Important: The map shows only partners with a location and Important: The partner map honours "Show on map".
```
vendor/bin/typo3 upgrade:run academicPartners_synchronizePartnerTranslations
```
Copied!

Neither wizard has to run again later. Should one have to, mark it undone first. TYPO3 13 marks a wizard undone with vendor/bin/typo3 upgrade:mark:undone <identifier>. TYPO3 12 has no such command: open Admin Tools > Upgrade > Upgrade Wizard, find the wizard under Wizards marked as done and choose Mark undone.

Adapt the configuration

The configuration of this extension changed shape in 2.4: one component per content element, a separate component for the styles.content.getContent override, the page TSconfig as a selectable entry and the folder Configuration/TsConfig/ spelled Configuration/TSconfig/. The complete list of paths and names is in Breaking: Site sets and static templates have been restructured.

Make the content elements selectable

The page TSconfig every installation includes hides the four content elements Partners List, Partners Map, Partnerships List and Partnerships Teaser now. The page TSconfig of a component brings its element back. Enable them on every site that uses them, with one of the two mechanisms and never with both:

TYPO3 13 with site sets: the site configuration depends on fgtclb/academic-partners. The set keeps the name it had in 2.3 and includes every component now, so a site that depends on it already needs no change. A site may name the component sets instead. It then adds fgtclb/academic-partners-content-load as well, or defines styles.content.getContent itself: the page template of the page type Partner renders that object and fails without it.
TYPO3 12, or TYPO3 13 without site sets: in the page record of every site root, field Include static Page TSconfig (from extensions) on the tab Resources, add Academic Partners: All components (academic_partners), or the entries of the components the site uses. The entry is new in 2.4, there is nothing to replace.

Existing content elements keep rendering in the frontend either way. In the backend, an existing element on a page where its component is not enabled keeps its type when it is saved. academic_base 2.4 shows the stored type as the selected option, followed by (not enabled on this page). The warning of the changelog entry, that saving such an element writes another CType, describes a state the 2.4 release of academic_base no longer has.

Select the static template again

This step concerns sites that include the TypoScript through a sys_template record, which is every site on TYPO3 12.

Version 2.3 registered the entry Academic Partners Page Setup under the extension key of academic_programs. A record that selected it stores EXT:academic_programs/Configuration/TypoScript/ and includes the TypoScript of that extension instead of this one, or nothing at all where academic_programs is not installed. The update does not rewrite the stored value, and no wizard does: it cannot be told apart from a deliberate selection of the programs entry. See Important: The static template and the backend layout are registered correctly.

Open the sys_template record of every site root, field Include TypoScript sets on the tab Advanced Options.
Add Academic Partners: All components (academic_partners). It carries the shared plugin settings, the rendering of the page type Partner and the styles.content.getContent override.
Take care of the stored value of 2.3. Where academic_programs is installed, the field shows it as Academic Programs: Shared plugin settings and page rendering (academic_programs). Remove that entry unless the site uses academic_programs, where it is the entry of that extension and stays. Where academic_programs is not installed, the field does not show the stored value at all, and saving the record drops it.

A site that selects component entries instead of All components adds Academic Partners: Content load override (academic_partners) as well, or defines styles.content.getContent itself. The page template of the page type renders that object and fails without it, and so does any template of the site package that renders it.

With the entry selected, a partner page renders the page template of this extension and the partnerships of the page for the first time on a site without site sets. Look at a partner page before you deploy.

Adjust imports of shipped files

A site package that imports a file of this extension by path checks every @import. An import of a missing file is silent, so a wrong path shows up as missing configuration, not as an error.

Configuration/TsConfig/ is Configuration/TSconfig/ now, and the wizard file Configuration/TsConfig/Wizards/NewContentElement.tsconfig is Configuration/TSconfig/Full/page.tsconfig.
Configuration/TypoScript/setup.typoscript no longer imports the styles.content.getContent override. Import Configuration/TypoScript/ContentLoad/setup.typoscript where the site needs it. The old file Configuration/TypoScript/Content/ContentLoad.typoscript is gone.
Configuration/Sets/AcademicPartners/constants.typoscript and setup.typoscript are gone. Import the files of Configuration/TypoScript/ instead.

Move label overrides

The templates read label overrides from the path the TYPO3 documentation names. An override under plugin.tx_academic_partners._LOCAL_LANG no longer has an effect. Move it to plugin.tx_academicpartners._LOCAL_LANG, or to plugin.tx_academicpartners_<plugin>._LOCAL_LANG for one plugin. This includes the labels of the filter form. See Important: Label overrides are read from the documented path and Important: Label overrides of the filters are read from the plugin path.

Extend the backend user groups on TYPO3 12

The partnership table declares its language column in TCA now, as an exclude field. On TYPO3 12, add tx_academicpartners_domain_model_partnership:sys_language_uid to the allowed excludefields of every backend user group whose members set the language of a partnership, tab Access Lists of the group record. See Important: Translations of partnerships keep their parent.

Adapt templates and assets

The stylesheet and the script of the map moved below frontend/, the four Leaflet files keep their paths:

Old path	New path
`EXT:academic_partners/Resources/Public/Css/map.css`	`EXT:academic_partners/Resources/Public/Css/frontend/map.css`
`EXT:academic_partners/Resources/Public/JavaScript/map.js`	`EXT:academic_partners/Resources/Public/JavaScript/frontend/map.js`

A copy of Templates/Partner/Map.html, or a site package that loads the files itself, takes over the new paths. See Breaking: The map assets are built and moved. Resources/Public/JavaScript/autocomplete.min.js is removed. Nothing of the extension loaded it, a site that does ships it in its own site package. See Breaking: Removed the unused autocomplete library.

Version 2.4 changes these templates and partials. A copy of one of them in a site package keeps rendering the copy, so compare each copy with the shipped file and take over the changes. The paths below are relative to Resources/Private/:

File	What changed	Entry
`Templates/Partner/Map.html`	Loads the moved map files, and only while there are partners to draw. Without them it renders a message instead of an empty map.	Breaking: The map assets are built and moved, Important: The map shows only partners with a location
`Templates/Partner/PartnershipsList.html`, `Templates/Partner/PartnershipsTeaser.html`	A partnership is grouped by `{partnership.role.uid} == {role.uid}`, otherwise a translated page loses partnerships. The partnerships without a role are rendered after the role groups, from the new variable `{partnershipsWithoutRole}`.	Important: Each partnership renders once per language, Important: Partnerships without a role are listed too
`Pages/AcademicPartner.html`	The categories are read from `{partner.attributes.allCategoriesByType}`. A copy taken only to repair that can be dropped.	Important: The partner page type renders its categories
`Partials/Partner/DemandCategories.html`	Offers the category types `plugin.tx_academicpartners.filter.categoryTypes` names, in that order, and puts the ones after `filter.visibleCount` into a More filters section with labels of its own.	Feature: Choose, order and label the partner filters, Important: Label overrides of the filters are read from the plugin path
`Pages/AcademicPartner.html`, `Partials/Partner/DemandCategories.html`, `Partials/Partner/DemandSorting.html`, `Partials/Partner/Item.html`, `Partials/Partner/ItemList.html`, `Partials/Partnerships/List/Item.html`, `Partials/Partnerships/Teaser/Item.html`	The translations pass the extension name `AcademicPartners` instead of `academic_partners`. A copy that keeps the old name does not see the label overrides of the previous section.	Important: Label overrides are read from the documented path
`Partials/Partner/SortingAndFilters.html`	Renders a submit button inside `<noscript>` for visitors without JavaScript.	Important: The filter form works under a security policy
`Backend/Partials/PageLayout/Doktype40.html`	Removed. It was never rendered. The page module shows the categories of a partner page through category_types now, which takes an override under `templates.fgtclb/category-types.<key>`.	Important: The page module shows the page categories

A site package that shipped Academicpartner.html as the page template of the page type renames it to AcademicPartner.html. The extension sets page.10.templateName itself now. See Important: The page template name of the academic partner page type is set explicitly.

Adapt your code

Code that extends or replaces PartnerDemand, the DemandFactory or the PartnerRepository takes the new flag showHiddenRecords into account. No signature changed. See Important: Extended PartnerDemand and demand handling.

Check the result

The new content element wizard offers the partner content elements on the pages of every site that uses them, and an existing element opens with its type.
A partner page renders its template, its content, its partnerships and its categories, and its page module shows the categories of the page.
The map leaves out partners without coordinates and partners whose Show on map is switched off, in every language. A site where editors switched partners off sees them disappear from the map now.
A role form lists its partnerships in the order it showed before the update, and saving a role no longer changes the order on a partner page.
A list or map that hides a part of its form keeps the preset of that part when a visitor uses the rest of the form, see Important: A hidden part of the form keeps the preset value. A sorting that was hidden only to keep the default categories can be shown again.
A list or map with two default categories of one category type shows only the partners that carry both, as before. The description of the field says so now, see Important: The description of Default categories names their rule.
A page whose partnerships partly have a role lists the partnerships without a role after the role groups, and so the partnerships of a hidden or deleted role. A role given to a partnership only to keep it visible can be removed again. Hide a partnership to take it off the page, see Important: Partnerships without a role are listed too.
Translated partnerships: the changelog entries Important: Translated partnerships keep their role and Important: Translations of partnerships keep their parent carry queries for translations that point at a translated role, duplicates and wrong translation parents. Delete the duplicates first, then save the default language records.
TYPO3 12: a partnership whose partner page was hidden or timed may have lost its partner on an earlier save. Choose the partner again, the select offers such partners now. See Important: The partner select offers hidden partners.