Upgrading from 2.4 to 3.0

Version 3.0 drops TYPO3 12, makes the three record tables of the study plan workspace aware, ships no stylesheet any more, loads the script from the template as an ES module, renders speaking classes and the shared icons of academic_base, and splits the template into partials with a markup contract of data attributes. Until the database is updated, the backend list of the study plan categories and every study plan fail. 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_study_plan 3.0 declares no new dependency of its own. It needs these packages. Upgrade them first or in the same deployment, in this order:

fgtclb/environment-state-manager 2.x, which academic_base 3.0 requires. Version 2.4 required 1.x. Composer updates it on its own. A classic installation updates environment_state_manager before it activates academic_base 3.0.
fgtclb/academic-base 3.0, the same release as this extension.

These changes have to ship in the same deployment as the update:

The database update, without which the backend list of the study plan categories and every study plan fail, see Update the database.
The rules of the site stylesheet for the study plan. From 3.0 on the site package styles the study plan, and without its rules a semester header shows both of its glyphs and the filter does not collapse, see Site stylesheet.

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.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 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/academic-study-plan':'~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 and academic_study_plan 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.

The tables tx_academicstudyplan_domain_model_category, tx_academicstudyplan_domain_model_semester and tx_academicstudyplan_domain_model_module are workspace aware now and get the columns t3ver_oid, t3ver_wsid, t3ver_state and t3ver_stage with an index. Until the columns are there, the backend list of the study plan categories and the frontend of every study plan fail with a database error. No stored record is changed. See Important: Study plan records are now workspace aware. The comparison also applies the changes of the index definitions TYPO3 13.4.35 and 14.3.7 bring.

The column credit_points of the semester and module tables is no longer declared in ext_tables.sql. TYPO3 derives it from the TCA, a decimal column with two decimals, as in 2.4. On MariaDB, MySQL and PostgreSQL the comparison leaves it alone. An installation that redefined the column in an ext_tables.sql of its own removes that definition before the comparison, because a declared column wins over the derived one. See Important: The credit point columns are derived from the TCA.

On SQLite two things differ:

vendor/bin/typo3 extension:setup can create the index over t3ver_oid and t3ver_wsid without adding the four columns, and reports success. Check afterwards that all three tables carry the four columns, and take the schema from a database built with the new state where they are missing.
The database analyzer can report "table … already exists" and "no such table: __temp__…" for the semester and module tables, because both changes rebuild those tables in one run. The tables end up complete with every value kept, and a second comparison offers nothing more.

Adapt the configuration

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. Run it on the staging copy right after the package update. For this extension it reports, among others, a site that depends on the alias set fgtclb/academic-study-plan-default, and a site that delivers this extension through its site set and a static template at once:

vendor/bin/typo3 academic:upgrade:check

With the extension key and a site it also lists the template overrides of the site that no longer match a file of this extension, or that are identical to the shipped file:

vendor/bin/typo3 academic:upgrade:check academic_study_plan --site=<site identifier>

Each finding, and what to do about it, is described in the upgrade check of academic_base.

Site sets

A site that depends on fgtclb/academic-study-plan-default keeps working. The set is an alias of fgtclb/academic-study-plan, which the upgrade check reports as a notice and which goes away in version 4.0. Depend on fgtclb/academic-study-plan instead, see What the sets contain.

Adapt templates and assets

Site stylesheet

The study plan ships no stylesheet any more. The file EXT:academic_study_plan/Resources/Public/Css/frontend/academic-study-plan.css of 2.4 is removed, and the page loads no stylesheet for the element. Style it in the site package. Three parts of the element do not work without rules of the site:

A semester header shows the expand and the collapse glyph at the same time. The stylesheet shows one of them.
The collapsible filter stays on screen while it is collapsed whenever a rule of the site gives the filter list a display. The stylesheet needs .ace-filter .ace-list[hidden] { display: none }.
The accordion of a narrow viewport and the highlighting of a category have no visible effect. The script only writes the classes open and highlighted.

The rules 2.4 shipped live on as an example, the stylesheet of the development instances of the academic extensions. Copy what the site needs, or the rules of the stylesheet the installation loaded so far, and adapt them to the theme. See Breaking: The study plan ships no stylesheet, Style the element and the example in An example.

Speaking classes

The templates carry speaking classes with the prefix ace- now, instead of the classes of the theme they were developed with. The content element keeps academic-study-plan, but loses container. The filter, the semesters, the modules and the dialog carry the classes the table of Breaking: Study plan templates carry speaking classes lists, the grid classes row and col stay. Move the selectors of the site stylesheet to the new classes. How the markup of the study plan is built up is described in Styling, the class system of all academic extensions in the Styling chapter of academic_base.

Icons

The icons of the study plan are renamed, and the three controls of the frontend are the shared action icons of academic_base now:

2.4 identifier	3.0 identifier
`academic-study-plan`	`tx-academicstudyplan-plugin-study-plan`
`academic-study-plan-category`	`tx-academicstudyplan-record-category`
`academic-study-plan-semester`	`tx-academicstudyplan-record-semester`
`academic-study-plan-module`	`tx-academicstudyplan-record-module`
`academic-study-plan-plus`	`tx-academicbase-action-expand`
`academic-study-plan-minus`	`tx-academicbase-action-collapse`
`academic-study-plan-close`	`tx-academicbase-action-close`

Replace the previous identifiers in TCA overrides, page TSconfig, templates and selectors such as .icon-academic-study-plan-plus. A site package that replaced a control registers its replacement under the 3.0 identifier in its Configuration/FrontendIcons.php, not in Configuration/Icons.php, and depends on academic_base. The replacement then shows in every academic extension that renders the icon. See Breaking: The study plan icons are renamed and the controls are frontend icons and The glyphs of a semester header.

The script

The script of the study plan is an ES module now, which the template of the content element loads with <f:asset.module>, and only on a page that renders a study plan. The TypoScript of the extension no longer adds it, or the stylesheet, to the page. Remove own includeCSS or includeJSFooter entries for the files of 2.4 below frontend/. A classic script tag does not run the module. See Breaking: The study plan assets are loaded by the template, as module.

An installation that overrode the template only to leave out the script, or to bring its own, sets plugin.tx_academicstudyplan.assets.js to off instead and drops the copy, see Skip the script.

Template overrides

One template file changed in 3.0, Resources/Private/Frontend/Default/Templates/AcademicStudyPlan.html, and four partials are new. A copy of the 2.4 template in a site package keeps rendering, but misses these changes. Compare it with the 3.0 files, or better, replace it with an override of the one partial it is really about. The paths below are relative to Resources/Private/:

File	What changed	Entry
`Frontend/Default/Templates/AcademicStudyPlan.html`	Renders the filter, the semesters, the modules and the dialogs through the partials `StudyPlan/Filter`, `StudyPlan/Semester`, `StudyPlan/Module` and `StudyPlan/ModuleDialog`, and marks every part the script drives with a `data-study-plan-*` attribute.	Feature: Study plan partials and a markup contract
`Frontend/Default/Templates/AcademicStudyPlan.html`	Loads the script with `<f:asset.module>` inside an `<f:if>` on `settings.assets.js`, and registers no stylesheet.	Skip the script
`Frontend/Default/Partials/StudyPlan/Filter.html`	Renders the item the script clones with the attribute `hidden`, so its placeholder text never shows.	Important: The study plan filter template item is hidden
`Frontend/Default/Partials/StudyPlan/Semester.html`, `Frontend/Default/Partials/StudyPlan/ModuleDialog.html`	Render the controls with `<ab:icon>` of academic_base and the 3.0 identifiers, no longer with `<core:icon>`.	The glyphs of a semester header
`Frontend/Default/Partials/StudyPlan/Semester.html`, `Frontend/Default/Partials/StudyPlan/Module.html`, `Frontend/Default/Partials/StudyPlan/ModuleDialog.html`	Receive `idPrefix` and start the dialog id with it, so a plan shown again through an "Insert records" element opens its own dialogs.	Important: A study plan shown again gets dialog ids of its own

The script still finds the parts of an override by the class names of 2.4 when it carries none of the data attributes, but that fallback is deprecated and is removed in version 4.0. Add the attributes on the elements The data attributes names. See Deprecation: The study plan class selectors.

The upgrade check with the extension key and the site lists the overrides of a site that no longer match a file of the extension, see The upgrade check.

Adapt your code

A script of your own

An installation that drives the study plan with a script of its own, with plugin.tx_academicstudyplan.assets.js switched off or from a copy of the template, takes the attribute hidden off every filter item it builds from the template item, as the shipped script does:

item.removeAttribute('hidden');

Without it, the filter shows no button at all. See Important: The study plan filter template item is hidden and Feature: The study plan script can be switched off.

Check the result

The backend list of the study plan categories opens, and a translated study plan renders. Both fail while the workspace columns are missing.
Existing study plans render with their semesters, modules and credit points. The new content element wizard offers the element as Study Plan now, with a new description, see Important: Content elements have new titles and descriptions.
The category, semester and module records show icons in the text colour of the backend, also in a dark colour scheme, see Important: Record icons follow the backend colour scheme.
A semester header shows one glyph, the filter highlights the modules of a category, and a module opens its dialog. The browser loads the module @fgtclb/academic-study-plan/frontend/academic-study-plan.js only on pages with a study plan, and no stylesheet of the extension.
On an installation that uses workspaces, the live site no longer shows semesters, modules or categories that only exist as a draft in a workspace, and a workspace preview shows the workspace state, see Important: The study plan frontend is now workspace aware.
The upgrade check exits with 0, without the extension key and with it for every site that renders a study plan, see The upgrade check.