Upgrading 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

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 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-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.

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.

vendor/bin/typo3 cache:flush

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 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

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

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.

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. 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 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/AcademicPrograms/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_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 and Important: Label overrides of the filters are read from the plugin path.

Replace a copied 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

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.

Adapt templates and assets

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
`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, Important: Label overrides of the filters are read from the plugin path
`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
`Partials/Program/SortingAndFilters.html`	Renders a submit button inside `<noscript>` for visitors without JavaScript.	Important: The filter form works under a security policy
`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

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.

Adapt your 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.
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.

Check the result

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. 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.
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.