Upgrading from 2.3 to 3.0 

This page takes an installation of academic_persons_edit 2.3 straight to 3.0, without the step to 2.4. Version 3.0 replaces the profile editing view in place. The content element keeps its type, but every Fluid file of the old form flow is gone, and the editor writes through a JSON page type that the site has to deliver. The page leaves out the 2.4 states that 3.0 replaces: the 2.4 adaptations of the Fluid files of the old form flow, see Breaking: Adapted frontend editing Fluid files and Breaking: Adapted frontend editing templates for contact record visibility, the moved editor configuration JavaScript/frontend/ckeditor.js, see Breaking: The editor configuration moved, the 2.4 constant renderContentElementHeader , see Important: The profile editing plugin leaves the content element header to the layout, and the 2.4 meaning of an empty list of accepted media types, see Important: An empty mime type list accepts every upload. 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_persons_edit 3.0 declares two new dependencies, typo3/cms-rte-ckeditor and typo3/html-sanitizer , see Important: New dependencies cms-rte-ckeditor and html-sanitizer. Neither adds a package to an installation: academic_persons requires rte_ckeditor already, and the TYPO3 core requires typo3/html-sanitizer . The extension also needs these academic 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 and academic_persons 3.0 require. Composer installs it on its own. A classic installation installs environment_state_manager 2.x before it activates either of them.
  • fgtclb/academic-base 3.0, the same release as this extension.
  • fgtclb/academic-persons 3.0, the same release as this extension. Its upgrade chapter has steps of its own, and its database update, its upgrade wizards and its settings migration are due in the same deployment.

academic_persons_sync 3.0 requires this extension and follows it in the same deployment, where installed.

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

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 wizards academicPersonsEdit_pluginContent and academicPersonsEdit_removeProfileSwitcherContent of this extension read the column tt_content.list_type , which TYPO3 14 removes, so they only run on TYPO3 13. The same holds for the content element wizard of academic_persons, which this extension requires, and for those of academic_jobs and academic_projects 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/academic-persons':'~3.0.0' \
    'fgtclb/academic-persons-edit':'~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, academic_persons and academic_persons_edit there, in this order. Keep rte_ckeditor active, the rich text fields of the editor load CKEditor 5 from it. 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.

Versions 2.4 and 3.0 of this extension change no table. Run the update all the same, it applies the changes of the index definitions TYPO3 13.4.35 and 14.3.7 bring, and academic_persons 2.4 and 3.0 change its tables, which the upgrade wizards of the next step require. Its upgrade chapter names what has to be checked before.

Run the upgrade wizards 

Run the wizards in this order, after the database update, and on TYPO3 13:

  1. academicPersonsEdit_pluginContent, Migrate plugin list element from academic_persons_edit to normal content elements, only if it is still offered.
  2. academicPersonsEdit_removeProfileSwitcherContent, Remove content elements of the removed academic_persons_edit profile switcher plugin.
  3. academicPersonsEdit_repairLocalizedProfileImages, Repair the profile image relations of academic profiles.
vendor/bin/typo3 upgrade:run academicPersonsEdit_pluginContent
vendor/bin/typo3 upgrade:run academicPersonsEdit_removeProfileSwitcherContent
vendor/bin/typo3 upgrade:run academicPersonsEdit_repairLocalizedProfileImages
Copied!

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 repair wizard is repeatable and never recorded as done.

The content element wizard 

academicPersonsEdit_pluginContent shipped with 2.x already and moves a profile editing content element stored as list with a list_type onto its own CType . An installation that ran it there has nothing more to do. TYPO3 14 no longer has tt_content.list_type , so the wizard has to run on TYPO3 13, before the core update. Replace own TypoScript, TSconfig or SQL that matches on list_type with a condition on CType . See Breaking: Extbase plugins require CType on TYPO3 v14.

The profile switcher 

The wizard Remove content elements of the removed academic_persons_edit profile switcher plugin, academicPersonsEdit_removeProfileSwitcherContent, is new in 2.4. The profile switcher has rendered nothing since version 2.1, and its content type is removed. The wizard sets every content element of it to deleted, with the CType academicpersonsedit_profileswitcher and as a legacy plugin with the list_type of that name. The records stay restorable from the recycler. An installation that never used the profile switcher gets nothing to do from it. See Breaking: Removed the profile switcher plugin, which also has the queries to look at the affected records first.

The profile image relations 

academic_persons 3.0 makes the profile image translatable, and a translation can carry an image of its own. The relations the image upload and the translation synchronisation of 2.x wrote do not always fit that. The wizard Repair the profile image relations of academic profiles, academicPersonsEdit_repairLocalizedProfileImages, is new in 3.0. It reduces duplicate references of a profile, corrects the relation counters, and sets the custom localization state on a translation that carries an image of its own, so that the next synchronisation keeps it. See Important: Repair wizard for profile image relations.

The wizard writes through the DataHandler and deletes no file. It skips workspace versions and acts in the live workspace, so publish a workspace with person records and run the wizard again afterwards. Run it before editors use the new editor of a multilingual site. Prefer the command line over the upgrade module for it.

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, and work through what it reports together with the next steps:

vendor/bin/typo3 academic:upgrade:check
Copied!

With the extension key and a site it also reports every template override of the site whose file this extension no longer ships, which is every override of the old form flow:

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

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

Make the content element selectable 

The site set and the static template are cut per component since 2.4, and the Edit Person’s Profiles content element is hidden for the whole installation until the page TSconfig of its component brings it back. See Breaking: Site sets and static templates have been restructured for the complete change.

  • Without a site set: add Academic Persons Edit: All components (academic_persons_edit) in the page record of every site root that offers profile editing, tab Resources, field Include static Page TSconfig (from extensions), see Include static page TSconfig. This entry did not exist in 2.3. Without it the content element is no longer offered in the backend.
  • With a site set: nothing to do. The set fgtclb/academic-persons-edit keeps its name and delivers the page TSconfig.

Use one mechanism per site, never a site set and a static template together, see Do not combine both.

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.

Static templates and imports 

The static template of version 2.3, stored as EXT:academic_persons_edit/Configuration/TypoScript, keeps delivering. It is offered as Academic Persons Edit: Path up to 2.3 (deprecated, use All components) now and will be removed in version 4.0. Replace it in the field Include TypoScript sets on the tab Advanced Options of the sys_template record with Academic Persons Edit: All components (academic_persons_edit), or depend on the set fgtclb/academic-persons-edit instead. See Deprecation: The static template path of version 2.3.

The same holds for an @import of Configuration/TypoScript/constants.typoscript or Configuration/TypoScript/setup.typoscript in a site package: it keeps working and is deprecated. Import the files of Configuration/TypoScript/ProfileEditing/ instead. Configuration/TSconfig/page.tsconfig and the files below Configuration/Sets/AcademicPersonsEdit/ were removed. Their content is in Configuration/TSconfig/ProfileEditing/page.tsconfig and in the set folders Configuration/Sets/Full/ and Configuration/Sets/ProfileEditing/. An @import of a missing file fails silently and shows up as missing configuration.

The page type of the editor 

The editor writes through a PAGE object with typeNum = 1733735 , named academicPersonsProfileEditingAjax . The site set fgtclb/academic-persons-edit-profile-editing, the sets that depend on it and the static templates of this extension deliver it. There was no such page type in 2.3.

  • A site package that copied the TypoScript of this extension instead of including the set or a static template has no such object. Include the delivered TypoScript, or add the object to the copy. The editor reports a missing page type above itself and in the TYPO3 log, it cannot repair it.
  • A PageType route enhancer maps typeNum 1733735.
  • A web application firewall or a reverse proxy lets the page type and the X-Requested-With header through.

See The page type of the JSON endpoints and Important: Profile editing is replaced in place.

The header of the content element 

The layout of the plugin rendered the header and the subheader of the content element in 2.3, twice where the content element layout of the site renders them as well. The editor of 3.0 renders no header of its content element. A site whose content element layout renders the header has it once now. A site whose layout renders no header loses it, and renders it through a content element layout of the site, as the entry shows. See Breaking: The profile editing plugin renders no content element header.

The constant plugin.tx_academicpersonsedit.view.layoutRootPath is removed, the editor renders without a Fluid layout.

The profile image upload 

An empty value of plugin.tx_academicpersonsedit.settings.editForm.profileImage.validation.allowedMimeTypes or ...validation.maxFileSize falls back to image/jpeg,image/png,image/webp and 2M now. In 2.3 an empty list of media types rejected every upload. A site that wants to accept other types or larger files lists them explicitly. See Breaking: Profile image upload validation always applies.

The settings of the editor 

The editor reads its fields from Configuration/AcademicPersons/Settings.yaml of academic_persons, which version 3.0 builds from sections. The contract form renders the fields of contracts.fields, and the address, email address and phone number forms those of contracts.contactSections.<section>.fields, in the order of the file. A field the file does not declare is neither rendered nor written. A site package with its own settings file declares the contract fields and the contact sections it wants, after the migration the upgrade chapter of academic_persons describes. See Breaking: Contract fields and contacts are configured as a unit and Profile editor and validation.

Extension configuration 

profile.autoCreateProfiles and profile.createProfileForUserGroups are removed from the extension configuration of this extension. They have had no effect since 2.1, where academic_persons took them over. Run the wizard academicPersons_MigrateProfileAutoCreateExtensionsConfiguration of academic_persons if it is still offered, it copies the values over, and drop the two options from the deployment configuration afterwards.

Labels 

  • A label override under plugin.tx_academic_persons_edit._LOCAL_LANG , or for the options of the select fields under plugin.tx_persons_edit._LOCAL_LANG , no longer has an effect. Move it to plugin.tx_academicpersonsedit._LOCAL_LANG , or to the path of the one plugin it is meant for. See Important: Label overrides are read from the documented path and Labels.
  • The labels of the old form flow are removed, 134 units of the locallang.xlf of 2.3, and the editor brings its own under the prefix profileEditing.*. An override or a translation of a removed unit has no effect any more. Compare the overrides with the shipped file.
  • The e-mail address field reads the unit emailAddress.email.label . An override keyed on emailAddress.emailAddress.label uses the new id. See Important: The e-mail address field has a label.
  • The help texts and the section headings of the editor read their overrides from plugin.tx_academicpersonsedit._LOCAL_LANG . See Important: Label overrides of the profile editor read the paths of the editor.
  • The backend labels of the relation between frontend users and profiles moved into academic_persons. An override of them through $GLOBALS['TYPO3_CONF_VARS']['SYS']['locallangXMLOverride'] targets the file of that extension now, as its upgrade chapter describes.

Adapt templates and assets 

The replaced view 

Every Fluid file of the form flow of 2.3 is removed: the layout Layouts/ProfileEdit.html, the templates of the profile, the contract, the email address, the phone number, the address and the profile information below Templates/, and the partials below Partials/Profile/Buttons/, Partials/Profile/Forms/, Partials/Profile/List/, Partials/Profile/Properties/ and Partials/Profile/Show/. Only Templates/Profile/List.html stays, rewritten. The new view is Templates/Profile/Index.html with its partials below Partials/Profile/. See Breaking: Replaced the profile editing view.

  • An override of a removed file is no longer rendered. Delete it, and re-apply what the project still wants on top of the new files. Overriding templates names the files that carry the hooks the script of the editor binds to.
  • A link to a removed controller or action answers with an error page. Link to the action index with the argument profileUid, or to the list of profiles.
  • The editor configuration Resources/Public/JavaScript/CKEditor.js of 2.3 is removed. The editor loads CKEditor 5 from rte_ckeditor itself.

The upgrade check with the extension key and a site reports every override of a removed file, see The upgrade check.

Classes and styles 

The templates carry the speaking ace-* classes the academic extensions share. Only the grid classes, the button classes and visually-hidden of Bootstrap stay. The scripts show and hide markup through the attribute hidden , not the class d-none. An override keeps the data-pe-* attributes and the ace-message of a field. See Breaking: Profile editing templates carry speaking classes and the chapter Styling.

The extension ships no stylesheet, as in 2.3. Only the development versions of 3.0 shipped one for the editor. Some parts of the new editor do not work without rules of the site: the image cropper, the elements hidden with [hidden] where a display utility of Bootstrap outranks the attribute, and the display of the custom elements. Copy those rules from the stylesheet of the development instances, see An example and Breaking: The profile editing plugin ships no stylesheet. On TYPO3 13.4.36, 14.3.8 and later the rich text fields need the interface stylesheet of CKEditor 5 as well, which the site links from EXT:rte_ckeditor, see The rich text editor.

Icons 

The editor renders the shared action and state icons of academic_base with its ab:icon ViewHelper. The academic-persons-edit-* identifiers are removed, five of them without a successor, and the content element icon is tx-academicpersonsedit-plugin-profile-editing now. A replacement of an editor icon moves to the Configuration/FrontendIcons.php of the site package, under the tx-academicbase-* identifier. The icons are inlined as <svg> , so a selector such as .t3js-icon img no longer matches. See Breaking: Profile editing renders the shared icon set and Icon identifiers.

Adapt your code 

  • The contract form has no Publish switch any more. ContractFormData loses $publish and isPublish() , and a save that still sends publish is refused with HTTP 422. Drop it from overrides, clients and constructor calls. See Breaking: The contract form has no "Publish" switch.
  • The five controllers of the contracts, the profile information and the contacts are removed, and ProfileController keeps only the actions of the new editor. AbstractActionController , UserSessionService and the five validators of the contract, address, email, phone number and profile information forms are removed as well, and so is ProfileFormData::createFromProfile() , deprecated since 2.3, see The replaced view. A project that completes or refuses a write of the editor listens to BeforeProfileEditingWriteEvent , see BeforeProfileEditingWriteEvent.
  • Code that extends or replaces the internal form data classes and sets a property the request did not submit registers the value with AbstractFormData::setPropertyOverride() , otherwise it is not applied. See Important: Form data transformation only maps submitted fields.
  • UnknownValidatorException and UnsuitableValidatorException moved to the namespace \FGTCLB\AcademicBase\Settings\Exception . See Important: Validator exceptions moved to EXT:academic_base.
  • The listener SyncChangesToTranslations takes its record synchronizer as $recordSynchronizer now. Code that creates it with the named argument recordSyncronizer: changes it, see the breaking change entry of academic_persons.

Check the result 

  • The upgrade check reports no override of a removed file, and exits with 0, without and with the extension key, see The upgrade check.
  • The new content element wizard offers Edit Person’s Profiles on the pages that should have it, see Important: Content elements have new titles and descriptions, and an existing profile editing content element opens in the backend with its own type.
  • No profile switcher content element is left, and the page module shows no element with an invalid type in its place.
  • The editor loads without the alert that the profile cannot be saved, a field can be saved, and the browser console shows no failed request to the page type 1733735.
  • The header of a profile editing content element appears once.
  • The image cropper can be dragged, and the regions the editor hides stay hidden.
  • A frontend user can edit each of its profiles. The editor accepts only profiles the frontend user is linked to in the default language of the profile, a link set only on a translation is ignored. See Important: The editor is limited to own profiles.
  • A profile image uploads, and a translated profile shows an image in every language. An upload in one language does not change the image of another.
  • The rich text fields start the editor, and its toolbar shows small icons in one row.