Upgrading from 2.3 to 3.0 

This page takes an installation of academic_programs 2.3 straight to 3.0, without the step to 2.4. Version 2.4 brings the selectable content elements, the static template, the page content and new paths of the shipped files. Version 3.0 runs on TYPO3 13 and 14 only, renders the program page inside the layout of the site, replaces the categories partial with the facts of a program, carries speaking classes, renames the icons, makes the controllers final and registers the content element Course Finder itself. The page leaves out the 2.4 states that 3.0 replaces: the deprecated file reference collection, see Deprecation: The file reference collection goes, and 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_programs 3.0 needs these packages. Upgrade them first or in the same deployment, in this order:

These changes have to ship in the same deployment as the update, because a site or a request 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 subclass or an XCLASS of one of the two program controllers stops with a fatal error. A registration of the content type academicprograms_programfinder in the site package collides with the one of this extension. Code that names the removed classes FileReferenceCollection or \Backend\Tca\Labels fails. 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 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/category-types':'~3.0.0' \
    'fgtclb/academic-programs':'~3.0.0'
Copied!

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_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
Copied!

Update the database 

vendor/bin/typo3 extension:setup
Copied!

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

The command creates and changes tables and columns and drops nothing. For this extension it adds two columns in 3.0, which TYPO3 derives from the TCA:

Column Change
pages.application_link , pages.application_link_label Added. The link to an application and its label, on the tab Program of a program page. A page shows no button until an editor sets a link. See Feature: Program pages link to an application.

An installation that added a column application_link of its own removes its TCA and its ext_tables.sql line for it, the data stays and the program page renders it. One that kept the link in a column of another name copies it into the new column once, the changelog entry has the query.

The comparison also applies the changes of the index definitions TYPO3 13.4.35 and 14.3.7 bring.

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 a controller and a stored path of 2.3 that no longer exists. 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
Copied!

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, Program/Categories.html among them:

vendor/bin/typo3 academic:upgrade:check academic_programs --site=<site identifier>
Copied!

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

Make the content elements selectable 

The page TSconfig every installation includes hides the content elements Course List, Course Data and the new Course Finder. 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-programs. The set keeps the name it had in 2.3 and includes every component, the finder set fgtclb/academic-programs-program-finder among them, 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 Programs: All components (academic_programs), 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 its changelog entry. 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.

The finder opens a program list with a selection applied, see Feature: A program finder content element and What the finder renders. A site that registered a finder of its own under its content type removes that registration first, see Adapt your code.

Check the static template 

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

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 defines styles.content.getContent , see Replace the global content object. Academic Programs: All components (academic_programs) carries the same TypoScript, and is the entry to select for a new site.

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.

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/Content/ContentLoad.typoscript is gone, without a successor, see Replace the global content object.
  • Configuration/Sets/AcademicPrograms/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 program page rendered it. The program page renders the content of its main column from the variable programContent of its own page object now, see Important: The program page renders its own content, and no academic extension defines styles.content.getContent any more, see Breaking: The content load component of programs is removed.

  • Move a customisation of styles.content.getContent that was meant for program pages, a content slide or another column for example, to page.10.variables.programContent , inside the condition on the program page type, see The content of a program 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_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.

Import the route enhancer 

Configuration/Yaml/Routes.yaml could not be imported up to 2.3, it was not valid YAML, see Important: The shipped route enhancer configuration can be imported. The enhancer of the Course List lives in Configuration/Routes/List.yaml now, maps the category filter and the sorting into the path, and translates the sorting values into the language of the site. The former file imports it.

config/sites/<site>/config.yaml 
imports:
  - resource: 'EXT:academic_programs/Configuration/Routes/List.yaml'
Copied!

A site that copied the enhancer of 2.3 into its own site configuration replaces the copy by that import. See Important: The route enhancer moved and translates its values and Feature: The route enhancer maps the filter.

The list answers a filter submission with a redirect to a URL that carries the selection. A route enhancer the site keeps for the program list must not declare defaults for the sorting, see Important: The route enhancer declares no default sorting and Feature: Program filter selections have a URL.

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: Program 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 program list and the program 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_academicprograms.view.partialRootPaths {
    -1 = EXT:academic_base/Resources/Private/Partials/
}
Copied!

See Breaking: Images render as a responsive picture.

Replace the renamed icons 

The icons of this extension are new drawings, registered in a way that follows the colour scheme of the backend and the colour of the text in the frontend.

  • The identifier academic-programs is gone. Replace it with tx-academicprograms-doktype-program where the page type is meant and with tx-academicprograms-plugin-programs where a content element is meant, in TCA, page TSconfig, templates and CSS selectors.
  • The credit points icon is a frontend icon of Configuration/FrontendIcons.php. A replacement of it is registered in the Configuration/FrontendIcons.php of the site package.
  • A path to a file below Resources/Public/Icons/CategoryTypes/ points at the new file of the changelog entry.

See Breaking: Icons renamed, credit points icon is a frontend icon. The category type icons in the facts render as an inline <svg> now, so CSS that addressed an <img> addresses the <svg> , see Breaking: Record and category icons follow the colour scheme.

Render program pages in the site layout 

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

  • A site package whose layout for program pages has another name sets plugin.tx_academicprograms.page.layout , see The layout of a program page.
  • plugin.tx_academicprograms.page.listPid names the page the link back to the program list leads to. Without it the page shows no link.
  • An override of Pages/AcademicProgram.html made to change one part moves that change to the matching partial below Program/Page/, see The parts of a program page, and the override goes. An override that stays renders no application link, which the partial Program/Page/CallToAction.html renders.
  • 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. See Important: The page template name of the academic program page type is set explicitly.

Render the facts 

The partial Program/Categories.html is removed. The program page, the Course Data content element and the card of the Course List render their facts through Program/Facts.html and Program/Facts/Item.html, from the field lists plugin.tx_academicprograms.facts.fields and card.fields . See Breaking: The partial Program/Categories.html has been removed and The facts of a program.

  • Move a change of one fact to an override of Program/Facts/Item.html, and a change of the whole list to an override of Program/Facts.html.
  • Set the field lists where the override changed which facts are shown or their order.
  • An override of a template that renders <f:render partial="Program/Categories" ... /> fails. Render Program/Facts there, and remove the override of Program/Categories.html.

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

File What changed Entry
Pages/AcademicProgram.html Renders the layout of the site and the partials below Program/Page/, among them the facts and the application link, and the content from {programContent} in place of styles.content.getContent . Render program pages in the site layout, Replace the global content object, Feature: Program pages link to an application
Templates/Details/Show.html, Partials/Program/Item.html Render the facts through Program/Facts.html. The item renders the image through Academic/Image.html of academic_base, and can show the most specific category of a type. Render the facts, Style the new markup, Feature: Program facts can show the most specific category
Templates/Program/List.html, Partials/Program/SortingAndFilters.html, Partials/Program/DemandCategories.html, Partials/Program/DemandSorting.html Carry the wrapper, the region, the submit button and the marks the module of the list reads to update the list in place, and load the module unless settings.assets.js switches it off. The selects have no onchange handler any more, and the extension allows none in the Content Security Policy. A copy that keeps the handler needs its hash in the csp.yaml of the site. Important: Overrides of the program list templates, Important: The filter form works under a security policy, Feature: The scripts of the program list and finder can be switched off
Templates/Program/List.html, Templates/Details/Show.html Render the header of the content element while renderContentElementHeader is switched on. Feature: The plugins can render the content element header
Partials/Program/SortingAndFilters.html Renders the new partials Program/ActiveFilters.html and Program/ResultCount.html. Feature: Active filter tags, a reset link and a result count
Partials/Program/DemandCategories.html Offers the category types the content element or plugin.tx_academicprograms.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 program filters, Feature: Integrators choose the filters of the program list, Feature: Own category types are named by their title
Partials/Program/Header.html Takes the class of the heading as class in place of positionClass . Style the new markup
Every file above, and Partials/Program/ItemList.html Speaking classes in place of the classes of a theme. The translations pass the extension name AcademicPrograms instead of academic_programs , otherwise they miss the label overrides of the configuration step. Style the new markup, Move label overrides
Partials/Program/Categories.html Removed. Render the facts
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, 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, Program/Categories.html among them, see The upgrade check.

Adapt your code 

  • ProgramController and DetailsController are final. A subclass, and an XCLASS of one of them, 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 program events or of the plugin view event, see Breaking: The program controllers are final and For developers.
  • This extension registers the content type academicprograms_programfinder with the plugin ProgramFinder now. A site package or project extension that registered a finder under these names removes its type item, its FlexForm, its configurePlugin() call, its controller code and its page TSconfig, in the same deployment as the update. Stored finder records keep their type and render with the finder of this extension. See Breaking: The content type academicprograms_programfinder is taken.
  • \FGTCLB\AcademicPrograms\Collection\FileReferenceCollection is removed. 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 Breaking: The file reference collection is removed.
  • \FGTCLB\AcademicPrograms\Backend\Tca\Labels is removed. Remove a label_userFunc that names it, it never changed a label, see Breaking: The unused TCA label class has been removed.
  • \FGTCLB\AcademicPrograms\DataProcessing\ProgramDataProcessor takes the facts builder, the data factory and the event dispatcher as constructor arguments. A subclass passes them on and is registered as a public service, or is replaced by a listener of ModifyProgramDataEvent . See Feature: Change the program list, finder and page by event.
  • Code that extends or replaces ProgramDemand , the DemandFactory or the ProgramRepository takes the flag showHiddenRecords into account, new since 2.4. See Important: Extended ProgramDemand and demand handling.
  • The FlexForm data structure of the Course List is one file now, Configuration/FlexForms/ProgramListSettings.xml. The files below Configuration/FlexForms/Core12/ and Core13/ are gone. Code of the site that names one of them by path names the new file. The field names are unchanged. See Important: The FlexForm data structure moved.

Check the result