Upgrading from 2.3 to 3.0

This page takes an installation of academic_partners 2.3 straight to 3.0, without the step to 2.4. Version 2.4 adds a database column, two upgrade wizards, selectable content elements and a static template of its own. Version 3.0 runs on TYPO3 13 and 14 only, renders the partner page inside the layout of the site, carries speaking classes, ships no map stylesheet, renames the icons and makes the controller final. The page leaves out the 2.4 states that 3.0 replaces: the map files below frontend/, see Breaking: The map assets are built and moved, and the content load component, which the 2.4 changelog entry on the restructured configuration names. Work through the sections in order. Skip a step that does not apply to the installation.

Before you start

Version 3.0 runs on TYPO3 13.4 from 13.4.35 on and on TYPO3 14.3 from 14.3.7 on, with PHP 8.2 or later.

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

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

These changes have to ship in the same deployment as the update, because a site or a request fails until they are made:

A site without site sets includes the page TSconfig of the components, or the content elements are not offered, see Make the content elements selectable.
A site with a sys_template record selects the static template again, or partner pages render without the TypoScript of this extension, see Select the static template again.
A subclass or an XCLASS of the partner controller, and a subclass of the partner repository that declares findAll(), stop with a fatal error, see Adapt your code.

The module paths on this page are those of TYPO3 13, where the upgrade runs.

Update TYPO3 first

Update TYPO3 to 13.4.35 or later while the site still runs 2.3, which supports TYPO3 13.4. Version 3.0 no longer installs on TYPO3 12, and Composer and the Extension Manager refuse it next to an older patch release of TYPO3 13.

Stay on TYPO3 13 until the upgrade is complete when the installation also has academic_jobs, academic_persons, academic_persons_edit or academic_projects. Their content element wizards read the column tt_content.list_type, which TYPO3 14 removes, so they only run on TYPO3 13. Move to TYPO3 14.3.7 or later once they have run.

See Breaking: Removed TYPO3 v12 support and Important: TYPO3 13.4.35 or 14.3.7 is required.

Update the package

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

On a classic installation, install environment_state_manager 2.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

vendor/bin/typo3 extension:setup

Or apply the changes in Admin Tools > Maintenance > Analyze Database Structure.

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

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. See Important: The link column of pages is nullable now.

The comparison also applies the changes of the index definitions TYPO3 13.4.35 and 14.3.7 bring.

Run the upgrade wizards

Both wizards are new since 2.4. They need the columns of the database comparison 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. Until it has run, a role form lists its partnerships in arbitrary order.
```
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. 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. A wizard that TYPO3 recorded as done is offered again once it is marked undone. TYPO3 13 marks a wizard undone with vendor/bin/typo3 upgrade:mark:undone <identifier>.

Adapt the configuration

The configuration of this extension is delivered per component since 2.4: one component per content element, the page TSconfig as a selectable entry and the folder Configuration/TsConfig/ spelled Configuration/TSconfig/. The complete list of paths and names is in the 2.4 changelog entry the introduction of this page links. The content load component that entry names was removed again in 3.0, see Replace the global content object.

The upgrade check

The console command academic:upgrade:check of academic_base reads the stored configuration of the installation and reports what no longer reaches the academic extensions. For this extension it reports an XCLASS of the controller and a stored path of 2.3 that no longer exists. Run it on the staging copy right after the package update, and again once the steps of this section are done:

vendor/bin/typo3 academic:upgrade:check

With the extension key and a site it also compares the override folders of the site with the shipped files and reports an override of a file the extension no longer ships:

vendor/bin/typo3 academic:upgrade:check academic_partners --site=<site identifier>

Each finding, and what to do about it, is described in the upgrade check of academic_base.

Make the content elements selectable

The page TSconfig every installation includes hides the four content elements Partner List, Partner Map, Partners Linked and Partner Logo Teaser. 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:

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, so a site that depends on it already needs no change. A site may name the component sets instead.
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.

Until a component is included, an existing content element of it keeps rendering and keeps its type: academic_base shows the stored type in the field Type followed by (not enabled on this page), and saving keeps it. The warning of the 2.4 changelog entry that saving such a record rewrites its type describes the state before a fix that academic_base 2.4 carries as well, see its changelog entry. A content element that a page TSconfig of your own already turned into another type is not repaired. Correct it by hand from its record history.

Select the static template again

This step concerns sites that include the TypoScript through a sys_template record.

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. 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 and the rendering of the page type Partner.
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.

With the entry selected, a partner page renders the page template of this extension 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/Content/ContentLoad.typoscript is gone, without a successor, see the next section.
Configuration/Sets/AcademicPartners/constants.typoscript and setup.typoscript are gone. Import the files of Configuration/TypoScript/ instead.

academic:upgrade:check reports an import of a missing file in a TypoScript record as typoscript-import and in page TSconfig as tsconfig-import.

Replace the global content object

Version 2.3 defined styles.content.getContent for every page of the site, through Configuration/TypoScript/setup.typoscript, and the partner page rendered it. In 3.0 the partner page renders the content of its main column from the variable partnerContent of its own page object, and no academic extension defines styles.content.getContent any more. See Breaking: Partner pages render their content without a global path.

Move a customisation of styles.content.getContent that was meant for partner pages to page.10.variables.partnerContent, inside the condition on the partner page type, see The content of a partner page.
A template of the site package that renders styles.content.getContent defines the object itself:
```
styles.content.getContent < styles.content.get
styles.content.getContent.select.where = {#colPos}=0
```
Copied!

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

The description of a page is an exclude field again, on partner pages as on every other page. Add it to Allowed fields of every backend user group that edits the description of pages or partners, or to its permission set. See Breaking: The page description is an exclude field again.

The partnership table declares its language column in TCA as an exclude field since 2.4. A backend user group whose members set the language of a partnership needs tx_academicpartners_domain_model_partnership:sys_language_uid in its allowed excludefields, tab Access Lists of the group record. A site that ran 2.3 on TYPO3 12 adds it. See Important: Translations of partnerships keep their parent.

Check own route enhancers

The partner list and map answer a filter submission with a redirect to a URL that carries the selection. A route enhancer of the site for these plugins must not declare defaults for the sorting: the redirect for the default sorting would otherwise end on the page URL without arguments, where the preset of the content element applies again. Remove such defaults, or import the enhancers of Configuration/Routes/List.yaml instead, see Feature: Partner filter selections have a URL and Feature: Route enhancers for the partner list and map.

Adapt templates and assets

Style the new markup

The templates of this extension carry speaking classes now, such as ace-item, ace-list, ace-attribute, ace-label and ace-value, in place of the card, list group and utility classes of a theme. The extension ships no styles for them. Move the selectors of the site stylesheet from the old classes to the new ones, the changelog entry lists them side by side, see Breaking: Partner templates carry speaking classes. Styling shows the markup of every view and links the stylesheet partial the development instances of the academic extensions use, An example.

The stylesheet of the map, Resources/Public/Css/map.css in 2.3, is removed. Without a stylesheet of the site, the map has no height and stays invisible. Give the map element a height and take over the two other rules of the removed file where the theme needs them, see Breaking: The partner map ships no stylesheet:

#map {
    height: 500px;
}

The images of the partner list, the partnerships and the partner page render as a <picture> through the image partial of academic_base. CSS that selects the image as a direct child of its container adjusts to the wrapper. A plugin view whose partial root paths the site replaced completely needs the path of academic_base below its own:

plugin.tx_academicpartners.view.partialRootPaths {
    -1 = EXT:academic_base/Resources/Private/Partials/
}

See Breaking: Images render as a responsive picture.

Replace the renamed icons

The icons of this extension are new drawings, registered in a way that follows the colour scheme of the backend and the colour of the text in the frontend. Their identifiers changed without an alias, academic-partners became five identifiers. Replace every identifier of 2.3 in TCA, page TSconfig, templates and code of the site, and register a replacement drawing under the new identifier. The category type icons keep their identifiers, but render as an inline <svg> in the frontend, so CSS that addressed an <img> addresses the <svg> now. See Breaking: Icons are renamed and follow the colour scheme and Important: Category type icons come from the frontend icon registry.

Load the map script as a module

Version 2.3 loaded Resources/Public/Css/map.css and Resources/Public/JavaScript/map.js as a classic script, next to the classic files of Leaflet and of the marker cluster plugin. In 3.0 the map script is an ES module, it imports Leaflet and the marker cluster plugin as modules, and the map stylesheet is gone. A site that uses the shipped templates needs to do nothing. An override of Templates/Partner/Map.html, of the new partial Partials/Partner/Map.html, or a site package that loads the script itself, replaces the script references and drops the one to map.css:

<f:asset.module identifier="@fgtclb/academic-partners/frontend/map.js" />

See Breaking: The map script is a module and Important: The partner map loads its libraries as modules. The classic files of Leaflet and of the marker cluster plugin stay until 4.0 for a site that loads them itself. Move such a reference to the module files, see Deprecation: The classic files of the map libraries.

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.

The map leaves out partners without coordinates and partners whose Show on map is switched off. A page template of the site that shows the map of one partner renders the partial with the argument partner in place of a map of its own, see Important: The map partial skips a partner it must not draw.

Render partner pages in the site layout

The page template of the partner page type renders the section Main of the layout Default of the site package, through five partials below Partner/Page/. A partner page shows the header, the navigation and the footer of the site now. See Breaking: Partner pages render inside the site layout.

A site package whose layout for partner pages has another name sets plugin.tx_academicpartners.page.layout, see The layout of a partner page.
An override of Pages/AcademicPartner.html made to change one part moves that change to the matching partial below Partner/Page/, see The parts of a partner page, and the override goes.
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. See Important: The page template name of the academic partner page type is set explicitly.

Compare template overrides

Versions 2.4 and 3.0 change 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 of 3.0 and take over the changes. The paths below are relative to Resources/Private/:

File	What changed	Entry
`Pages/AcademicPartner.html`	Renders the layout of the site and the partials below `Partner/Page/`, the content from `{partnerContent -> f:format.raw()}` in place of `styles.content.getContent`, and the categories from `{partner.attributes.allCategoriesByType}`.	Render partner pages in the site layout, Replace the global content object, Important: The partner page type renders its categories
`Templates/Partner/Map.html`	Renders the map through the new partial `Partner/Map.html`, which loads the map module and passes the map settings of the site as data attributes.	Load the map script as a module, Feature: The partner map is configurable per site
`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
`Templates/Partner/List.html`, `Templates/Partner/Map.html`, `Templates/Partner/PartnershipsList.html`, `Templates/Partner/PartnershipsTeaser.html`	Render the header of the content element while `renderContentElementHeader` is switched on.	Feature: The plugins can render the content element header
`Partials/Partner/DemandCategories.html`	Offers the category types `plugin.tx_academicpartners.filter.categoryTypes` names, in that order, puts the ones after `filter.visibleCount` into a More filters section, and labels an own category type by its title.	Feature: Choose, order and label the partner filters, Feature: Own category types are named by their title
`Partials/Partner/SortingAndFilters.html`	Renders the new partials `Partner/ActiveFilters.html` and `Partner/ResultCount.html`, and a submit button inside `<noscript>` for visitors without JavaScript.	Feature: Active filter tags, a reset link and a result count, Important: The filter form works under a security policy
`Partials/Partner/ItemList.html`	Renders one page of partners and the new partial `Partner/Pagination.html` while the pagination is enabled.	Feature: The partner list can be paginated
`Partials/Partner/Item.html`, `Partials/Partnerships/List/Item.html`, `Partials/Partnerships/Teaser/Item.html`	Render the image through `Academic/Image.html` of academic_base, the category icons with the `ab:icon` ViewHelper and the title of an own category type.	Style the new markup, Replace the renamed icons, Feature: Own category types are named by their title
`Partials/Partner/Header.html`	Takes the class of the heading as `class` in place of `positionClass`, and wraps it in `<header class="ace-header">`.	Style the new markup
Every file above, and `Partials/Partner/DemandSorting.html`	Speaking classes in place of the classes of a theme. The translations pass the extension name `AcademicPartners` instead of `academic_partners`, otherwise they miss the label overrides of the configuration step.	Style the new markup, Move label overrides
`Backend/Partials/PageLayout/Doktype40.html`	Removed. It was never rendered. The page module shows the categories of a partner page through category_types, which takes an override under `templates.fgtclb/category-types.<key>`.	Important: The page module shows the page categories

The upgrade check with the extension key and a site reports an override of a file the extension no longer ships, see The upgrade check.

Adapt your code

\FGTCLB\AcademicPartners\Controller\PartnerController is final. A subclass, and an XCLASS of it, stop with a fatal error. Remove them, and the configurePlugin() call or the XCLASS registration that points at them, in the same deployment as the update. Move what they did to a listener of the partner events or of the plugin view event, see Breaking: The partner controller is final and For developers.
PartnerRepository::findAll() declares QueryResultInterface as its return type. A subclass that overrides it with ?QueryResult stops with a fatal error. Declare the new type, see Breaking: The partner repository declares what it returns.
Code that extends or replaces PartnerDemand, the DemandFactory or the PartnerRepository takes the flag showHiddenRecords into account, new since 2.4. See Important: Extended PartnerDemand and demand handling.
The FlexForm data structures are one file per plugin now, Configuration/FlexForms/ListSettings.xml and Configuration/FlexForms/MapSettings.xml. The files below Configuration/FlexForms/Core12/ and Core13/ are gone. Code of the site that names one of them by path names the new file. The field names are unchanged. See Important: The FlexForm data structures moved.

Check the result

The upgrade check exits with 0, without and with the extension key, see The upgrade check. Run it again after each configuration step, and in the deployment pipeline.
The new content element wizard offers Partner List, Partner Map, Partners Linked and Partner Logo Teaser on the pages of every site that uses them, see Important: Content elements have new titles and descriptions, and an existing element opens with its type.
A partner page renders inside the layout of the site, with its content, its categories and its address, and its page module shows the categories of the page.
The partner list, the map and the partnerships look as the site intends, with the speaking classes, and the map has a height. The map leaves out partners without coordinates and partners whose Show on map is switched off, in every language.
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.
A list or map keeps its default categories of the category types its filter does not offer, see Important: A filter keeps the default categories of other types.
Editors that edit partner pages can still edit the description.
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.
Partnerships that lost their page or their role through a workspace publish in 2.x: the changelog entry Important: Partnerships keep their page and role when either is published carries the queries that find them.
An installation that ran on TYPO3 12: a partnership whose partner page was hidden or timed may have lost its partner on an earlier save. Choose the partner again, see Important: The partner select offers hidden partners.