---
title: "Upgrading from 2.4 to 3.0"
manual: "Academic Partners"
version: "main"
permalink: "https://docs.typo3.org/permalink/fgtclb/academic-partners:upgrade-from-2-4-to-3-0@main"
source: "Upgrade/From24To30.rst"
rendered: "2026-10-26T19:20:19+00:00"
---

# Upgrading from 2.4 to 3.0 {#upgrade-from-2-4-to-3-0}

Version 3.0 of **academic_partners** runs on TYPO3 13 and 14 only. The
partner page renders inside the layout of the site and carries its content
itself, so the content load set of 2.4 is gone. The templates carry speaking
classes in place of the classes of a theme, the map ships no stylesheet and
loads its script as a module, the icons are renamed, and the controller is
final. Work through the sections in order. Skip a step that does not apply to
the installation.

## Before you start {#upgrade-from-2-4-to-3-0-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`](https://packagist.org/packages/fgtclb/environment-state-manager) 2.x, which
    **academic_base** 3.0 requires in place of 1.x. Composer updates it
    on its own. A classic installation updates
    **environment_state_manager** before it updates
    **academic_base**.
-   [`fgtclb/academic-base`](https://packagist.org/packages/fgtclb/academic-base) 3.0, the same release as this extension.
-   [`fgtclb/category-types`](https://packagist.org/packages/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 that depends on `fgtclb/academic-partners-content-load` answers
    every page with HTTP 500, see
    [Remove the content load set](https://docs.typo3.org/permalink/fgtclb/academic-partners:upgrade-from-2-4-to-3-0-content-load@main).
-   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](https://docs.typo3.org/permalink/fgtclb/academic-partners:upgrade-from-2-4-to-3-0-code@main).

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

## Update TYPO3 first {#upgrade-from-2-4-to-3-0-typo3}

Update TYPO3 to 13.4.35 or later while the site still runs 2.4, 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](https://docs.typo3.org/permalink/fgtclb/academic-partners:breaking-removed-typo3-v12-support@main) and
[Important: TYPO3 13.4.35 or 14.3.7 is required](https://docs.typo3.org/permalink/fgtclb/academic-partners:important-minimum-typo3-versions@main).

## Update the package {#upgrade-from-2-4-to-3-0-package}

```bash
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, update **environment_state_manager** to 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`.

```bash
vendor/bin/typo3 cache:flush
```

## Update the database {#upgrade-from-2-4-to-3-0-database}

```bash
vendor/bin/typo3 extension:setup
```

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

This extension changes no column in 3.0. The comparison applies the changes of
the index definitions TYPO3 13.4.35 and 14.3.7 bring.

Version 3.0 adds no upgrade wizard for this extension. The two wizards of 2.4
have nothing left to do on an installation that ran them with 2.4.

## Adapt the configuration {#upgrade-from-2-4-to-3-0-configuration}

### The upgrade check {#upgrade-from-2-4-to-3-0-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 a dependency on
the removed content load set and an XCLASS of the controller, but not a
subclass that is registered another way. Run it on the staging copy right
after the package update, and fix what it reports before the deployment:

```bash
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:

```bash
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](https://docs.typo3.org/p/fgtclb/academic-base/main/en-us/UpgradeCheck/Index.html#upgrade-check)
of **academic_base**.

### Remove the content load set {#upgrade-from-2-4-to-3-0-content-load}

The partner page renders the content of its main column from the variable
`partnerContent` of its own page object now. The set
`fgtclb/academic-partners-content-load`, its static template
**Academic Partners: Content load override (academic_partners)** and
the file [`Configuration/TypoScript/ContentLoad/setup.typoscript`](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/Configuration/TypoScript/Index.html#file-extension-configuration-typoscriptsetup-typoscript) are
removed, and no academic extension defines
`styles.content.getContent` any more. See
[Breaking: Partner pages render their content without a global path](https://docs.typo3.org/permalink/fgtclb/academic-partners:breaking-partners-content-load-set-removed@main).

1.  Remove `fgtclb/academic-partners-content-load` from the
    `dependencies` of every site configuration and of every set of the
    site package, in the same deployment as the update. A site that depends on
    the aggregate `fgtclb/academic-partners` needs no change.
1.  Remove the static template **Academic Partners: Content load
    override (academic_partners)** from every `sys_template` record, and an
    `@import` of the removed file from the site package.
1.  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](https://docs.typo3.org/permalink/fgtclb/academic-partners:partner-page-content@main).
1.  A template of the site package that renders
    `styles.content.getContent` defines the object itself:

    ```typoscript
    styles.content.getContent < styles.content.get
    styles.content.getContent.select.where = {#colPos}=0
    ```

`academic:upgrade:check` reports a site that depends on the removed set as
`unavailable-set`, the removed static template as
`static-template` and an import of the removed file as
`typoscript-import`.

### Extend the backend user groups {#upgrade-from-2-4-to-3-0-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](https://docs.typo3.org/permalink/fgtclb/academic-partners:breaking-1790839520@main).

### Check own route enhancers {#upgrade-from-2-4-to-3-0-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](https://docs.typo3.org/permalink/fgtclb/academic-partners:feature-1790226100@main) and [Feature: Route enhancers for the partner list and map](https://docs.typo3.org/permalink/fgtclb/academic-partners:feature-1791043402@main).

## Adapt templates and assets {#upgrade-from-2-4-to-3-0-templates}

### Style the new markup {#upgrade-from-2-4-to-3-0-stylesheets}

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](https://docs.typo3.org/permalink/fgtclb/academic-partners:breaking-partners-speaking-frontend-classes@main). [Styling](https://docs.typo3.org/permalink/fgtclb/academic-partners:styling@main) shows the
markup of every view and links the stylesheet partial the development instances
of the academic extensions use, [An example](https://docs.typo3.org/permalink/fgtclb/academic-partners:styling-example@main).

The stylesheet of the map 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](https://docs.typo3.org/permalink/fgtclb/academic-partners:breaking-partner-map-ships-no-stylesheet@main):

```css
#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:

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

See [Breaking: Images render as a responsive picture](https://docs.typo3.org/permalink/fgtclb/academic-partners:breaking-partners-images-render-as-picture@main).

### Replace the renamed icons {#upgrade-from-2-4-to-3-0-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.4 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](https://docs.typo3.org/permalink/fgtclb/academic-partners:breaking-partners-record-and-category-icons-follow-the-colour-scheme@main) and
[Important: Category type icons come from the frontend icon registry](https://docs.typo3.org/permalink/fgtclb/academic-partners:important-partners-category-icons-come-from-the-frontend-icon-registry@main).

### Load the map script as a module {#upgrade-from-2-4-to-3-0-map-module}

The map script is an ES module now, and it imports Leaflet and the marker
cluster plugin as modules as well. A site that uses the shipped templates needs
to do nothing. An override of `Templates/Partner/Map.html` or of the new
partial `Partials/Partner/Map.html`, or a site package that loads the
script itself, replaces the script reference and drops the one to
`map.css`:

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

See [Breaking: The map script is a module](https://docs.typo3.org/permalink/fgtclb/academic-partners:breaking-ace-392-academic-partners-map-module@main) and
[Important: The partner map loads its libraries as modules](https://docs.typo3.org/permalink/fgtclb/academic-partners:important-1790623331@main). The classic files of Leaflet and of the marker
cluster plugin below `Resources/Public/JavaScript/` and
`Resources/Public/Css/` 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](https://docs.typo3.org/permalink/fgtclb/academic-partners:deprecation-1790623332@main).

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, so a
partner without coordinates or with **Show on map** switched off is
left out, see [Important: The map partial skips a partner it must not draw](https://docs.typo3.org/permalink/fgtclb/academic-partners:important-ace-770-academic-partners-map-partial@main).

### Render partner pages in the site layout {#upgrade-from-2-4-to-3-0-page}

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](https://docs.typo3.org/permalink/fgtclb/academic-partners:breaking-partner-page-renders-inside-the-site-layout@main).

-   A site package whose layout for partner pages has another name sets
    `plugin.tx_academicpartners.page.layout`, see
    [The layout of a partner page](https://docs.typo3.org/permalink/fgtclb/academic-partners:partner-page-layout@main).
-   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](https://docs.typo3.org/permalink/fgtclb/academic-partners:partner-page-partials@main), and the override goes.
-   A path the site set at the key `100` inside the condition on the partner
    page type moves to `50`, or to a key above it to win over the extension.

### Compare template overrides {#upgrade-from-2-4-to-3-0-overrides}

Version 3.0 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 |
| --- | --- | --- |
| `Pages/AcademicPartner.html` | Renders the layout of the site and the partials below `Partner/Page/`, and the content from `{partnerContent -> f:format.raw()}` in place of `styles.content.getContent`. | [Render partner pages in the site layout](https://docs.typo3.org/permalink/fgtclb/academic-partners:upgrade-from-2-4-to-3-0-page@main), [Remove the content load set](https://docs.typo3.org/permalink/fgtclb/academic-partners:upgrade-from-2-4-to-3-0-content-load@main) |
| `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](https://docs.typo3.org/permalink/fgtclb/academic-partners:upgrade-from-2-4-to-3-0-map-module@main), [Feature: The partner map is configurable per site](https://docs.typo3.org/permalink/fgtclb/academic-partners:feature-1790618147@main) |
| `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](https://docs.typo3.org/permalink/fgtclb/academic-partners:feature-1790440962@main) |
| `Partials/Partner/SortingAndFilters.html` | Renders the new partials `Partner/ActiveFilters.html` and `Partner/ResultCount.html`. | [Feature: Active filter tags, a reset link and a result count](https://docs.typo3.org/permalink/fgtclb/academic-partners:feature-1790946474@main) |
| `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](https://docs.typo3.org/permalink/fgtclb/academic-partners:feature-1790272109@main) |
| `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](https://docs.typo3.org/permalink/fgtclb/academic-partners:upgrade-from-2-4-to-3-0-stylesheets@main), [Replace the renamed icons](https://docs.typo3.org/permalink/fgtclb/academic-partners:upgrade-from-2-4-to-3-0-icons@main), [Feature: Own category types are named by their title](https://docs.typo3.org/permalink/fgtclb/academic-partners:feature-1791035983@main) |
| `Partials/Partner/DemandCategories.html` | Labels an own category type by its title. | [Feature: Own category types are named by their title](https://docs.typo3.org/permalink/fgtclb/academic-partners:feature-1791035983@main) |
| `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](https://docs.typo3.org/permalink/fgtclb/academic-partners:upgrade-from-2-4-to-3-0-stylesheets@main) |
| Every file above, and `Partials/Partner/DemandSorting.html` | Speaking classes in place of the classes of a theme. | [Style the new markup](https://docs.typo3.org/permalink/fgtclb/academic-partners:upgrade-from-2-4-to-3-0-stylesheets@main) |

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](https://docs.typo3.org/permalink/fgtclb/academic-partners:upgrade-from-2-4-to-3-0-upgrade-check@main).

## Adapt your code {#upgrade-from-2-4-to-3-0-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](https://docs.typo3.org/permalink/fgtclb/academic-partners:breaking-1791043406@main) and [For developers](https://docs.typo3.org/permalink/fgtclb/academic-partners:developers@main).
-   `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](https://docs.typo3.org/permalink/fgtclb/academic-partners:breaking-partner-repository-find-all-return-type@main).
-   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](https://docs.typo3.org/permalink/fgtclb/academic-partners:important-partners-flexform-data-structures-moved@main).

## Check the result {#upgrade-from-2-4-to-3-0-check}

-   The upgrade check exits with `0`, without and with the extension key,
    see [The upgrade check](https://docs.typo3.org/permalink/fgtclb/academic-partners:upgrade-from-2-4-to-3-0-upgrade-check@main). Run it again after each
    configuration step, and in the deployment pipeline.
-   The content elements are offered as **Partner List**,
    **Partner Map**, **Partners Linked** and
    **Partner Logo Teaser** now, see
    [Important: Content elements have new titles and descriptions](https://docs.typo3.org/permalink/fgtclb/academic-partners:important-content-element-titles-and-descriptions@main).
-   Every page of a site answers, none with HTTP 500.
-   A partner page renders inside the layout of the site, with its content,
    its categories and its address.
-   The partner list, the map and the partnerships look as the site intends,
    with the speaking classes, and the map has a height.
-   Editors that edit partner pages can still edit the description.
-   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](https://docs.typo3.org/permalink/fgtclb/academic-partners:important-partner-list-keeps-default-categories-of-other-types@main).
-   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](https://docs.typo3.org/permalink/fgtclb/academic-partners:important-partnerships-keep-their-page-on-publish@main) carries the
    queries that find them. Select the page or the role again, or add the
    partnership anew.