Upgrading from 2.3 to 3.0

This page takes an installation of academic_projects 2.3 straight to 3.0, without the step to 2.4. Version 2.4 brings the upgrade wizards, the selectable content elements and new paths of the shipped files. Version 3.0 runs on TYPO3 13 and 14 only, renders the project page inside the layout of the site, renames the department category type of this extension to project_department, carries speaking classes, replaces the icons and makes the controller final. The page leaves out the 2.4 state that 3.0 replaces: 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_projects 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, a request or a command 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 Configuration/CategoryTypes.yaml of the site package that changes or declares the type department of the group projects stops TYPO3 while it loads the category types, see Rename the department category type.
A subclass or an XCLASS of the project controller stops with a fatal error, and so does code that names the renamed sorting constant, 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. The content element wizard academicProjects_pluginUpgradeWizard of this extension reads the column tt_content.list_type, which TYPO3 14 removes, so it only runs on TYPO3 13. The same holds for the content element wizards of academic_jobs, academic_persons and academic_persons_edit when the installation also has them. 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-projects':'~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_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

Update the database

vendor/bin/typo3 extension:setup

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

This extension changes no column in 2.4 or 3.0. The comparison applies the changes of the index definitions TYPO3 13.4.35 and 14.3.7 bring. Run it all the same before the wizards of the next section, which need every table and column of the installation in place.

Run the upgrade wizards

Run the two wizards by name on TYPO3 13.

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 reads tt_content.list_type, which TYPO3 14 no longer has, so it runs before the site moves to TYPO3 14. Once the database comparison of TYPO3 14 has removed the column, the wizard finds nothing to do and is recorded as done, and nothing records any more which plugin such a content element was. Configuration of the site that matches these plugins on list_type matches on CType instead. See Breaking: Extbase plugins require CType on TYPO3 v14.
```
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 with 2.3 has it recorded as done, and TYPO3 does not offer it again. Mark it undone first. For a wizard that was never recorded as done, the command fails with a message, which is harmless. Then run the wizard:
```
vendor/bin/typo3 upgrade:mark:undone academicProjects_flexFormUpgradeWizard
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.

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

The department category type is moved by a console command, see Rename the department category type.

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, but neither a subclass that is registered another way nor the category type file. 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_projects --site=<site identifier>

Each finding, and what to do about it, is described in the fgtclb/academic-base:upgrade-check of academic_base.

Make the content elements selectable

The page TSconfig every installation includes hides the content elements Projects and Selected Projects. 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-projects. 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 Projects: All components (academic_projects), 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 fgtclb/academic-base:important-ace-666-academic-base. 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.

Check the static template

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

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 keeps working, but it no longer defines styles.content.getContent, see Replace the global content object. Academic Projects: All components (academic_projects) carries the same TypoScript, and is the entry to select for a new site.

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, see Important: The backend layout is registered for every installation.
Configuration/TypoScript/Content/ContentLoad.typoscript is gone, without a successor, see Replace the global content object.
Configuration/Sets/AcademicProjects/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 project page rendered it. In 3.0 the project page renders the content of its main column from the variable projectContent of its own page object, and no academic extension defines styles.content.getContent any more. See Breaking: Project pages render their content without a global path.

Move a customisation of styles.content.getContent that was meant for project pages to page.10.variables.projectContent, inside the condition on the project page type, see The content of a project 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_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.

Rename the department category type

The department type of this extension is project_department now, because academic_programs declares a type department as well and a category stores its type without the group. Its label key and its icon identifier follow. See Breaking: The projects department type is renamed.

Replace department with project_department in every Configuration/CategoryTypes.yaml of the site that changes or removes the type of the group projects, in the same deployment as the update. Not before it: 2.3 has no project_department to change.
After the update and the cache flush, move the stored categories:
```
vendor/bin/typo3 academic:projects:department:migrate
```
Copied!
The command lists the categories it cannot decide on. Open each of them in the backend and set its type. It can be run again. A site that removed the projects department in its CategoryTypes.yaml does not run it.
Replace department with project_department in plugin.tx_academicprojects.filter.categoryTypes and in the templates of the site. Search the site package for sys_category.projects.department and category_types.projects.department as well.
Flush the page cache.

Check own route enhancers

The project lists 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: Project filter selections have a URL and Feature: Route enhancers for the project lists.

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: Project 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 images of the project list and the project 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_academicprojects.view.partialRootPaths {
    -1 = EXT:academic_base/Resources/Private/Partials/
}

See Breaking: Images render as a responsive picture.

Replace the icons

The project page type and the two content elements have icons of their own, tx-academicprojects-doktype-project and tx-academicprojects-plugin-projects, in place of the core icon actions-code-merge. CSS that addressed them through that identifier names the new one. The category type icons keep their identifiers, but are new drawings from new files and render as an inline <svg> in the frontend, so CSS that addressed an <img> addresses the <svg> now, and a path to a file below Resources/Public/Icons/CategoryTypes/ points at the new file. See Breaking: Project icons are replaced and follow the colour scheme and Important: Category type icons come from the frontend icon registry.

Render project pages in the site layout

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

A site package whose layout for project pages has another name sets plugin.tx_academicprojects.page.layout, see The layout of a project page.
An override of Pages/AcademicProject.html made to change one part moves that change to the matching partial below Project/Page/, see The parts of a project page, and the override goes.
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. See Important: The page template name of the academic project 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, see Overriding templates. The paths below are relative to Resources/Private/:

File	What changed	Entry
`Pages/AcademicProject.html`	Renders the layout of the site and the partials below `Project/Page/`, the content from `{projectContent -> f:format.raw()}` in place of `styles.content.getContent`, the categories from `{project.attributes.allCategoriesByType}`, and the page record from `{page}` or `{data}`.	Render project pages in the site layout, Replace the global content object, Important: The project page type renders its categories, Important: Project page reads the page record from page
`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
`Templates/Project/List.html`	Renders the header of the content element while `renderContentElementHeader` is switched on.	Feature: The project lists can render the content element header
`Partials/Project/SortingAndFilters.html`	Renders the new partials `Project/ActiveFilters.html` and `Project/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/Project/Item.html`	Renders the image through `Academic/Image.html` of academic_base, the category icons with the `ab:icon` ViewHelper, the title of an own category type, and the state of the project when the content element asks for it.	Style the new markup, Replace the icons, Feature: Own category types are named by their title, Feature: The state of a project on its card
`Partials/Project/DemandCategories.html`	Offers the category types `plugin.tx_academicprojects.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 project filters, Feature: Own category types are named by their title
`Partials/Project/Header.html`	Takes the class of the heading as `class` in place of `positionClass`.	Style the new markup
Every file above, and `Partials/Project/DemandActiveState.html`, `Partials/Project/DemandSorting.html`, `Partials/Project/ItemList.html`	Speaking classes in place of the classes of a theme. The translations pass the extension name `AcademicProjects` instead of `academic_projects`, otherwise they miss the label overrides of the configuration step.	Style the new markup, Move label overrides
`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, 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\AcademicProjects\Controller\ProjectController 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 project events, see Breaking: The project controller is final and For developers.
SortingOptions::SORT_BY_STARTDATE_desc is renamed to SortingOptions::SORT_BY_STARTDATE_DESC, without an alias. Its value and every stored sorting stay as they are. See Breaking: The descending start date constant is renamed.
Code that extends or replaces ProjectDemand, the DemandFactory or the ProjectRepository takes the flag showHiddenRecords into account, new since 2.4. See Important: Extended ProjectDemand and demand handling.
\FGTCLB\AcademicProjects\ViewHelpers\Format\ReplaceViewHelper renders through render() 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 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.
vendor/bin/typo3 academic:projects:department:migrate lists no category left to decide on.
The new content element wizard offers Projects and Selected Projects 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 project page renders inside the layout of the site, with its content and its categories, the department among them. Links in its short description and funders resolve, and its page module shows the categories of the page.
The project lists look as the site intends, with the speaking classes. 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 keeps its preset categories of the category types its filter does not offer, see Important: A filter keeps the preset categories of other types.
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 Selected Projects content element shows the translated projects. See Important: Selected projects are translated in free fallback mode.