Upgrading from 2.3 to 2.4

Version 2.4 delivers the configuration of academic_projects per component, hides its content elements until a site enables them and resolves the links in the rich text of a project. Its FlexForm upgrade wizard migrates the plugin settings of older project lists for the first time, so it has to run again where it ran before. 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_projects 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.

On TYPO3 12, make sure every site that renders projects defines lib.parseFunc_RTE, before the update. The project page and the project list render the short description and the funders through <f:format.html> now, which fails without it. Fluid Styled Content and most site packages define it, TYPO3 13 defines it for every site. Check it in Site Management > TypoScript > Active TypoScript. See Important: The rich text of a project resolves its links.

Update the package

composer require -W \
    'fgtclb/academic-base':'~2.4.0' \
    'fgtclb/category-types':'~2.4.0' \
    'fgtclb/academic-projects':'~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_projects 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

Run the upgrade wizards

This extension adds no database column in 2.4. Both wizards require the missing tables and columns of the installation to be added anyway. upgrade:run adds them before it runs a wizard, Admin Tools > Upgrade > Upgrade Wizard asks for it first.

Run the two wizards by name:

academicProjects_pluginUpgradeWizard, Migrate academic_projects plugins from "list_type" to "CType". It turns the Insert plugin content elements of the plugins academicprojects_projectlist and academicprojects_projectlistsingle into content elements of the type of the same name. It is unchanged in 2.4 and has nothing to do on an installation that ran it before.
```
vendor/bin/typo3 upgrade:run academicProjects_pluginUpgradeWizard
```
Copied!
academicProjects_flexFormUpgradeWizard, Migrate the plugin settings of academic_projects project lists stored before 2.0. It rewrites the settings of 1.x and early 2.0 project lists: settings.hide_completed_projects becomes settings.activeState, settings.filter.options becomes settings.hideFilter and settings.sorting.options becomes settings.hideSorting. A new setting that a save in the backend stored already is kept. Up to 2.3 the wizard migrated no record at all. See Important: The FlexForm upgrade wizard migrates records and Important: FlexForm upgrade wizard migrates the setting name of 1.x.

It reads the Insert plugin elements of 1.x as well, so the two wizards can run in either order, also together in one bare vendor/bin/typo3 upgrade:run. Up to 2.3 it read the content elements the plugin wizard creates only, and a bare upgrade:run recorded it as done before it had anything to read. See Important: FlexForm upgrade wizard migrates "Insert plugin" elements of 1.x.

An installation that ran it before has it recorded as done, and TYPO3 does not offer it again. TYPO3 13 marks a wizard undone with vendor/bin/typo3 upgrade:mark:undone academicProjects_flexFormUpgradeWizard. TYPO3 12 has no such command: open Admin Tools > Upgrade > Upgrade Wizard, find the wizard under Wizards marked as done and choose Mark undone. For a wizard that was never marked done, the TYPO3 13 command fails with a message, which is harmless. Then run the wizard:
```
vendor/bin/typo3 upgrade:run academicProjects_flexFormUpgradeWizard
```
Copied!
Running it again is safe. It only rewrites a FlexForm that still holds one of the old setting names, and it is offered only while one does.

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 Projects and Projects (selected) 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-projects. 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-projects-content-load as well, or defines styles.content.getContent itself: the page template of the page type Project 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 Projects: All components (academic_projects), 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.

Complete 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 Projects, keeps its stored value EXT:academic_projects/Configuration/TypoScript/ and is called Academic Projects: Shared plugin settings and page rendering (academic_projects) now. It no longer carries the styles.content.getContent override that 2.3 included with it, and the page template of the page type Project renders that object. Without it, a project page fails.

Open the sys_template record of every site root, field Include TypoScript sets on the tab Advanced Options, and replace the entry with Academic Projects: All components (academic_projects). Alternatively add Academic Projects: Content load override (academic_projects) next to it, or define styles.content.getContent in the site package.

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/TsConfig/page.tsconfig is gone. It carried nothing but a comment. The backend layout of the page type is part of the page TSconfig every installation includes now, see Important: The backend layout is registered for every installation.
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/AcademicProjects/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_projects._LOCAL_LANG no longer has an effect. Move it to plugin.tx_academicprojects._LOCAL_LANG, or to plugin.tx_academicprojects_<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.

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, see Overriding templates. The paths below are relative to Resources/Private/:

File	What changed	Entry
`Pages/AcademicProject.html`, `Partials/Project/Item.html`	The short description, and on the page the funders as well, are rendered with `<f:format.html>` instead of `<f:format.raw>`, so that their links resolve.	Important: The rich text of a project resolves its links
`Pages/AcademicProject.html`	The categories are read from `{project.attributes.allCategoriesByType}`.	Important: The project page type renders its categories
`Pages/AcademicProject.html`	The heading falls back to the title of the page record taken from `{page}` or `{data}`.	Important: Project page reads the page record from page
`Partials/Project/DemandCategories.html`	Offers the category types `plugin.tx_academicprojects.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 project filters, Important: Label overrides of the filters are read from the plugin path
`Pages/AcademicProject.html`, `Partials/Project/DemandActiveState.html`, `Partials/Project/DemandCategories.html`, `Partials/Project/DemandSorting.html`, `Partials/Project/Item.html`, `Partials/Project/ItemList.html`	The translations pass the extension name `AcademicProjects` instead of `academic_projects`. 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/Project/SortingAndFilters.html`	Renders a submit button inside `<noscript>` for visitors without JavaScript.	Important: The filter form works under a security policy
`Backend/Partials/PageLayout/Doktype30.html`	Removed, and so is `ext_typoscript_setup.typoscript`, which registered it. It was never rendered. The page module shows the categories of a project 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 Academicproject.html as the page template of the page type renames it to AcademicProject.html. The extension sets page.10.templateName itself now. See Important: The page template name of the academic project page type is set explicitly.

Adapt your code

Code that extends or replaces ProjectDemand, the DemandFactory or the ProjectRepository takes the new flag showHiddenRecords into account. No signature changed. See Important: Extended ProjectDemand and demand handling.
\FGTCLB\AcademicProjects\ViewHelpers\Format\ReplaceViewHelper renders through render() now instead of the static renderStatic(), and declares content, substring and replacement as mixed. A subclass that overrides or calls renderStatic() moves to render(). Templates are not affected, see Important: The replace view helper declares its argument types.

Check the result

The new content element wizard offers Projects and Projects (selected) on the pages of every site that uses them, and an existing element opens with its type.
A project page renders its template, its content and its categories, links in its short description and funders resolve, and its page module shows the categories of the page.
A project list of 1.x shows or hides completed projects as it did before, and its filter and sorting forms are shown or hidden as configured.
A list that hides a part of its form keeps the preset of that part when a visitor uses the rest of the form, a list of running projects with a hidden state select shows running projects only, see Important: A hidden part of the form keeps the preset value.
A list shows a project only when it carries every selected category, as before, and not when it carries only a subcategory of one. The description of the field says so now, see Important: The description of Categories names their rule.
A list filtered by Active lists projects without an end date now, so a paginated list can grow by some entries. See Important: Projects without an end date are now active.
On a site language with fallbackType: free, the Projects (selected) content element shows the translated projects. See Important: Selected projects are translated in free fallback mode.