---
title: "Upgrading from 2.3 to 2.4"
manual: "Academic Programs"
version: "main"
permalink: "https://docs.typo3.org/permalink/fgtclb/academic-programs:upgrade-from-2-3-to-2-4@main"
source: "Upgrade/From23To24.rst"
rendered: "2026-10-17T08:47:58+00:00"
---

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

Version 2.4 delivers the configuration of **academic_programs** per
component and hides its content elements until a site enables them. The program
page renders its content through a variable of its own page object now, instead
of the global `styles.content.getContent`, and the update brings no
database change and no upgrade wizard for this extension. Work through the
sections in order. Skip a step that does not apply to the installation.

## Before you start {#upgrade-from-2-3-to-2-4-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_programs** 2.4 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) 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`](https://packagist.org/packages/fgtclb/academic-base) 2.4, the same release as this extension.
-   [`fgtclb/category-types`](https://packagist.org/packages/fgtclb/category-types) 2.4, the same release as this extension.

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

```bash
composer require -W \
    'fgtclb/academic-base':'~2.4.0' \
    'fgtclb/category-types':'~2.4.0' \
    'fgtclb/academic-programs':'~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](https://docs.typo3.org/permalink/fgtclb/academic-programs:important-1790796667@main).

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_programs** 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
```

## Adapt the configuration {#upgrade-from-2-3-to-2-4-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](https://docs.typo3.org/permalink/fgtclb/academic-programs:breaking-site-sets-and-static-templates-restructured@main).

### Make the content elements selectable {#upgrade-from-2-3-to-2-4-content-elements}

The page TSconfig every installation includes hides the content elements
**Program List** and **Program Details** 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-programs`. 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.
-   **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 Programs: All
    components (academic_programs)**, 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.

### Check the static template {#upgrade-from-2-3-to-2-4-static-template}

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

The entry of 2.3, **Academic Programs Page Setup**, keeps its stored
value `EXT:academic_programs/Configuration/TypoScript/` and is called
**Academic Programs: Shared plugin settings and page rendering
(academic_programs)** now. It keeps working, but it no longer carries the
`styles.content.getContent` override that 2.3 included with it.

The program page does not need the override any more. A template of the site
package that renders `styles.content.getContent` does, unless
another extension or the site package defines it. In that case replace the
entry with **Academic Programs: All components (academic_programs)**,
or add **Academic Programs: Content load override
(academic_programs)** next to it, in the field **Include TypoScript
sets** on the tab **Advanced Options** of the template record.

The static template entry of **academic_partners** 2.3 stored the same
value as the entry of this extension, so a template record that selected it
shows the entry of this extension now. The upgrade chapter of
**academic_partners** has a step to remove it by hand where the site
does not use this extension. Where it does, the entry stays.

### Move customisations of the program page content {#upgrade-from-2-3-to-2-4-program-page-content}

The page template of the page type **Program** renders the
variable `page.10.variables.programContent` now, which the
extension defines on program pages only. A customisation of
`styles.content.getContent` that was meant for program pages, a
content slide or another column for example, no longer reaches them. Move it
into the same condition on `programContent`, see
[Important: The program page renders its own content](https://docs.typo3.org/permalink/fgtclb/academic-programs:important-program-page-renders-its-own-content@main).

### Adjust imports of shipped files {#upgrade-from-2-3-to-2-4-imports}

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.
    `Configuration/TsConfig/page.tsconfig` is
    `Configuration/TSconfig/Full/page.tsconfig`, and the backend layout
    moved from `Configuration/TsConfig/Page/BackendLayouts/` to
    `Configuration/TSconfig/BackendLayouts/`.
-   [`Configuration/TypoScript/setup.typoscript`](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/Configuration/TypoScript/Index.html#file-extension-configuration-typoscriptsetup-typoscript) no longer imports the
    `styles.content.getContent` override. Import
    [`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) where the
    site needs it. The old file
    `Configuration/TypoScript/Content/ContentLoad.typoscript` is gone.
-   [`Configuration/Sets/AcademicPrograms/constants.typoscript`](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/Configuration/Sets/Index.html#file-set-constants-typoscript) and
    `setup.typoscript` are gone. Import the files of
    `Configuration/TypoScript/` instead.

### Move label overrides {#upgrade-from-2-3-to-2-4-label-overrides}

The templates read label overrides from the path the TYPO3 documentation
names. An override under `plugin.tx_academic_programs._LOCAL_LANG`
no longer has an effect. Move it to
`plugin.tx_academicprograms._LOCAL_LANG`, or to
`plugin.tx_academicprograms_<plugin>._LOCAL_LANG` for one plugin.
This includes the labels of the filter form. See
[Important: Label overrides are read from the documented path](https://docs.typo3.org/permalink/fgtclb/academic-programs:important-label-overrides-use-the-documented-path@main) and
[Important: Label overrides of the filters are read from the plugin path](https://docs.typo3.org/permalink/fgtclb/academic-programs:important-1790383007@main).

### Replace a copied route enhancer {#upgrade-from-2-3-to-2-4-route-enhancer}

`Configuration/Yaml/Routes.yaml` could not be imported up to 2.3, it was
not valid YAML. It can be imported now and maps the sorting of the program list
into the path:

**config/sites/\<site>/config.yaml**

```yaml
imports:
  - resource: 'EXT:academic_programs/Configuration/Yaml/Routes.yaml'
```

A site that copied the enhancer of 2.3 into its own site configuration replaces
the copy by that import. A copy that stays needs the `plugin`
`ProgramList`, the `routes` list, and the `requirements` and
`aspects` of the shipped file, otherwise it enhances nothing. See
[Important: The shipped route enhancer configuration can be imported](https://docs.typo3.org/permalink/fgtclb/academic-programs:important-1787055000@main).

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

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 |
| --- | --- | --- |
| `Pages/AcademicProgram.html` | Renders `{programContent -> f:format.raw()}` in place of `<f:cObject typoscriptObjectPath="styles.content.getContent"/>`. A copy that keeps the old line depends on the content load override of the previous section. | [Important: The program page renders its own content](https://docs.typo3.org/permalink/fgtclb/academic-programs:important-program-page-renders-its-own-content@main) |
| `Partials/Program/DemandCategories.html` | Offers the category types `plugin.tx_academicprograms.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 program filters](https://docs.typo3.org/permalink/fgtclb/academic-programs:feature-1790383004@main), [Important: Label overrides of the filters are read from the plugin path](https://docs.typo3.org/permalink/fgtclb/academic-programs:important-1790383007@main) |
| `Pages/AcademicProgram.html`, `Partials/Program/Categories.html`, `Partials/Program/DemandCategories.html`, `Partials/Program/DemandSorting.html`, `Partials/Program/Item.html`, `Partials/Program/ItemList.html` | The translations pass the extension name `AcademicPrograms` instead of `academic_programs`. 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](https://docs.typo3.org/permalink/fgtclb/academic-programs:important-label-overrides-use-the-documented-path@main) |
| `Partials/Program/SortingAndFilters.html` | Renders a submit button inside `<noscript>` for visitors without JavaScript. | [Important: The filter form works under a security policy](https://docs.typo3.org/permalink/fgtclb/academic-programs:important-ace-924-academic-programs@main) |
| `Backend/Partials/PageLayout/Doktype20.html` | Removed, with its registrations `templates.typo3/cms-backend.1730990129` and `templates.typo3/cms-backend.academic-programs`. It was never rendered. The page module shows the categories of a program page through **category_types** now, which takes an override under `templates.fgtclb/category-types.<key>`. | [Important: The page module shows the page categories](https://docs.typo3.org/permalink/fgtclb/academic-programs:important-1789660802@main) |

A site package that shipped `Academicprogram.html` as the page template
of the page type renames it to `AcademicProgram.html`. The extension sets
`page.10.templateName` itself now. See
[Important: The page template name of the academic program page type is set explicitly](https://docs.typo3.org/permalink/fgtclb/academic-programs:important-1786968000@main).

## Adapt your code {#upgrade-from-2-3-to-2-4-code}

-   `\FGTCLB\AcademicPrograms\Collection\FileReferenceCollection` is
    deprecated, and calling it raises a deprecation notice. Read the file
    references through
    `\TYPO3\CMS\Core\Resource\FileRepository::findByRelation()`. Which
    references come back differs in hidden and workspace records, the entry
    lists how. See [Deprecation: The file reference collection goes](https://docs.typo3.org/permalink/fgtclb/academic-programs:deprecation-file-reference-collection@main).
-   Code that extends or replaces `ProgramDemand`, the
    `DemandFactory` or the `ProgramRepository` takes the new flag
    `showHiddenRecords` into account. No signature changed. See
    [Important: Extended ProgramDemand and demand handling](https://docs.typo3.org/permalink/fgtclb/academic-programs:important-ace-250-academic-programs@main).

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

-   The new content element wizard offers **Program List** and
    **Program Details** on the pages of every site that uses them, and
    an existing element opens with its type.
-   A program page renders its template and the content of its main column,
    and its page module shows the categories of the page.
-   Pages of the site package that render
    `styles.content.getContent` still render their content.
-   A list 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](https://docs.typo3.org/permalink/fgtclb/academic-programs:important-hidden-program-form-parts-keep-their-presets@main). A sorting
    that was hidden only to keep the default categories can be shown again.
-   A list with two default categories of one category type shows only the
    programs that carry both, as before. The description of the field says so
    now, see [Important: The description of Default categories names their rule](https://docs.typo3.org/permalink/fgtclb/academic-programs:important-program-default-categories-description@main).
-   On PostgreSQL, programs that are equal in the chosen ordering may change
    their relative order once, they are ordered by uid now. See
    [Important: List ordering ties are broken by uid](https://docs.typo3.org/permalink/fgtclb/academic-programs:important-list-ordering-ties-are-broken-by-uid@main).