Upgrade 

Delete the old CSV export file 

The backend module streams the CSV export as download now. Earlier versions stored it publicly accessible in public/typo3temp/tx_clubdirectory/export.csv. Delete this file and its directory, as it contains the mail addresses, addresses and phone numbers of all exported clubs:

rm -rf public/typo3temp/tx_clubdirectory/

The export contains the clubs of the selected page or folder only, if the backend user has access to it. Values starting with =, +, - or @ are prefixed with a single quote, so spreadsheet applications do not execute them as formula.

CSV export format 

The CSV export follows RFC 4180 now: fields are separated by comma instead of semicolon and enclosed in double quotes instead of single quotes. Double quotes in values are doubled, lines end with CRLF and the file is UTF-8 encoded without byte order mark. Adapt scripts or imports, which process the export. In spreadsheet applications use the import of text/CSV files and choose UTF-8 and comma, if they do not detect them automatically.

Usergroup is checked on the server 

The site setting clubdirectory.userGroup controlled the rendering of the templates only. Now the actions of the Management plugin to create, edit and update clubs are denied with the 403 error handling of the site for anonymous visitors and for frontend users, which are not member of this group. The mail links with a valid moderation token keep working without login.

Check, that the owners of existing clubs are members of this usergroup. Additionally restrict the access of the management page to this usergroup in the page properties.

Activation via confirmation form 

The activate link of the mails points to the new action confirmActivation of the Management plugin. It shows a summary of the club and a button, which activates the club via POST. A GET request of the action activate does not activate the club anymore, it redirects to the confirmation.

If you override the mail templates Templates/Management/Update.html and Templates/Map/Create.html, change the action of the activate link from activate to confirmActivation. To change the confirmation page, override Templates/Management/ConfirmActivation.html. Its form sends the club UID as argument clubUid to the action activate.

Requirements 

clubdirectory requires jweiland/maps2 in version 12.2.1 or higher now:

composer req jweiland/clubdirectory:^9.0 jweiland/maps2:^12.2.1

Please also read the upgrade notes of maps2, if you update maps2, too.

Database: upgrade wizard first, then the database analyzer 

File ext_tables.sql has been removed. TYPO3 13 creates all tables and columns from TCA now. Some column types change: website, path_segment and the text columns get bigger types, district, club and addresses become NOT NULL and the relation and file counters become unsigned.

Column barrier_free of table tx_clubdirectory_domain_model_address changes from VARCHAR to SMALLINT. In strict SQL mode this change fails, if there are records with an empty or non-numeric value in this column.

Please execute the upgrade wizard clubdirectory_barrierFreeToIntegerUpdate first. It sets all invalid values to 0. After that use Analyze Database Structure in Admin Tools > Maintenance (or vendor/bin/typo3 extension:setup) to change the column types.

vendor/bin/typo3 upgrade:run clubdirectory_barrierFreeToIntegerUpdate
vendor/bin/typo3 extension:setup

New plugins: Management and Search 

The former single plugin Clubdirectory has been split into three plugins (content element types):

Clubdirectory (clubdirectory_clubdirectory)

List and detail view of clubs. Existing content elements keep this type and their FlexForm settings.

Club Directory Management (clubdirectory_management)

List of own clubs, form to create and edit a club, map positioning of new clubs and activation of clubs by the administrator.

Club Directory Search (clubdirectory_search)

Search form and search results.

There is no automatic migration, as the new plugins usually belong onto their own pages:

1. Insert a content element of type Club Directory Management on the page, where frontend users should manage their clubs.
2. Insert a content element of type Club Directory Search on the page, where the search results should be shown.
3. Configure the pages in the site settings of the site set jweiland/clubdirectory: clubdirectory.pidOfListPage, clubdirectory.pidOfDetailPage, clubdirectory.pidOfSearchResults and clubdirectory.pidOfManagementPage.

The links to the management, the redirects after saving a club and the edit and activate links of the notification mails are built with these settings. See Site settings and Club management and moderation.

If you have extended the controllers of clubdirectory or registered your own routes, please check your implementation. The actions listMyClubs, new, create, edit, update and activate have been moved from ClubController to ManagementController and the former search action is SearchController::listSearchResults now. The actions edit and update of MapController have been removed. The map of an existing club is edited in the club form of the Management plugin.

Extension configuration 

The notification mails to the administrator need a receiver and a sender. Please set emailToAddress in the extension settings. Check emailFromAddress and emailFromName, too, if there is no default sender in the mail settings of TYPO3. If a value is missing, saving a club in frontend fails with an exception, when the mail is sent.

Further set poiCollectionPid to the storage folder for the POI records which are created from the club addresses.

The map links of the detail view point to the page in the site setting clubdirectory.pidOfMaps2Plugin. Add the storage folder of the POI records to the storage folders of the maps2 plugin on this page. Otherwise the map shows no marker.

Owners and district of translated clubs 

The columns fe_users (Assign Frontend Users) and district of table tx_clubdirectory_domain_model_club are excluded from translation now (l10n_mode = exclude). Translated clubs use the owners and the district of the club in default language. The backend does not show these fields in translated records anymore.

Existing translations still contain their own, often empty values in the database. DataHandler synchronizes them on the next save of the club in default language. Please save all translated clubs in default language once, either in the backend or with your own script using DataHandler. Until then, a translated club may show no district and its owners may not get the edit link.

Site setting updateReferenceIndex removed 

The site setting clubdirectory.updateReferenceIndex has been removed. The site set always sets persistence.updateReferenceIndex = 1. To disable it, override plugin.tx_clubdirectory.persistence.updateReferenceIndex with your own TypoScript.

Extension setting userGroup moved to the site settings 

The extension setting userGroup has been moved to the site setting clubdirectory.userGroup. The template variable allowedUserGroup has been removed, use {settings.userGroup} in your own templates instead. Set the UID of the usergroup of the club owners in the site settings of your site, the default is 1.

The setting controls the visibility of the links to create a new club and to list the own clubs ( <f:security.ifHasRole> in Partials/Club/InsertEditLinks.html) and of the list in Templates/Management/ListMyClubs.html. Users not in this group get a message, that they have no access to this page.

The setting is not an access check on the server. A logged-in frontend user outside of this group can still call the actions to create a club directly. Restrict the access of the management page to the same usergroup in the page properties. See Access control and error pages.

Search property subCategory removed 

The deprecated property subCategory of the search model has been removed. The methods Search::getSubCategory() and Search::setSubCategory() do not exist anymore. If you use them in your own templates or code, use Search::getCategory() and Search::setCategory() instead.

Links and search forms have to submit the category as search[category] instead of search[subCategory].

Old URLs still containing search[subCategory] do not result in an exception. The parameter is ignored, so the search results are not filtered by this category anymore.

Page TSconfig removed 

The extension does not add TCEFORM page TSconfig based on the extension settings rootCategory and userGroup anymore. Without it, the backend offers the categories on root level in the plugin and the club records and all frontend users in the field Assign Frontend Users.

Add the page TSconfig to your site package to restore the previous restrictions, see Page TSconfig for categories and frontend users. The extension setting rootCategory only affects the category lists in the frontend now.

Page cache of list and detail pages 

The list and detail pages are tagged with the cache tags of the clubs and are flushed after saving a club. You can remove a TCEMAIN.clearCacheCmd, which you have configured for these pages only because of clubdirectory. See Moderation flow.

Template overrides 

If you have overridden templates or partials of clubdirectory in your site package, please compare them with the original files. Especially:

• The templates of the management actions have been moved from Templates/Club/ to Templates/Management/ (Edit, ListMyClubs, New, Update). Templates/Club/Search.html has been moved to Templates/Search/ListSearchResults.html. The new template Templates/Search/Show.html renders the search form.
• All sections of the partial Partials/Club/FormFields.html have been removed: renderTextProperty, renderSelectProperty, renderTextareaProperty, renderCheckboxProperty, renderMaps2Property, renderAddresses, renderAddressProperties, renderLogo, renderImages, renderLabel and renderHelpMessage. Every field is written out now, so you can adjust each field on its own. Overrides calling one of these sections have to be adapted.
• Logo and images use the file upload handling of Extbase. Use <f:form.upload property="logo"/> and <f:form.upload property="images" multiple="1"/> instead of the former indexed properties like logo.0 or images.1. Existing files are removed with <f:form.uploadDeleteCheckbox> .
• The address type has no default anymore. Address blocks without an address type are skipped. A chosen address type requires street, ZIP and city and a club needs at least one address.
• Links and forms pointing to the management or search actions need the arguments controller, pluginName and pageUid, e.g. pluginName="Management" and pageUid="{settings.pidOfManagementPage}".
• The mail templates Templates/Management/Update.html and Templates/Map/Create.html have to pass the argument moderationToken to the edit and activate links. The edit template Templates/Management/Edit.html has to submit the token as hidden field. Without the token the administrator gets an "access denied" page, see Club management and moderation.
• The site setting clubdirectory.feJavaScript and the jQuery UI dialog script for form hints have been removed. If you have used this setting to include your own JavaScript, include it in your site package now.
• Partials/Club/FormFields.html contains the new select field district. The actions new and edit of the Management plugin assign the variable districts.
• The detail link in Partials/Club/List.html sets the arguments controller="Club", pluginName="Clubdirectory" and extensionName="Clubdirectory", as the partial is rendered by all three plugins. Without them, the detail links of the search results and of the own clubs do not work.
• Partials/Club/Properties.html shows the categories and the tags of the club.
• The condition of the "last" link in Partials/Component/Pagination.html uses {paginator.currentPageNumber} now. ClubPagination does not provide the current page number.

Rights checkbox of checkfaluploads 

The original templates do not contain the rights checkbox of jweiland/checkfaluploads anymore. If checkfaluploads is installed, clubdirectory still adds its validator to the uploads of logo and images of the Management plugin. Without a checked rights checkbox every upload is rejected.

Add the rights checkbox to your template override of Partials/Club/FormFields.html in your site package, as described in the developer manual of checkfaluploads. clubdirectory registers the validator with the property paths club.logo and club.images, so the checkboxes have to be submitted with these names:

tx_clubdirectory_management[club][logo][rights]
tx_clubdirectory_management[club][images][rights]

Access control, moderation and error pages 

• Only frontend users assigned to a club and backend administrators are allowed to edit a club. All other requests stop with the 403 error handling of the site.
• A club is activated by the administrator with the signed link of the notification mail only. Owners can not activate their own clubs anymore. Links of mails sent before the update and links of older mails of a changed club do not work anymore. Activate such clubs in the backend instead.
• The detail view shows the 404 error handling of the site for hidden, deleted or unknown clubs instead of an empty page.

Please configure the error handling of your site for the status codes 403 and 404. Read Club management and moderation for details.

Routing and path segments 

New clubs created in frontend get a path segment generated like DataHandler does: the title, made unique with a suffix like -1. The UID is not part of the path segment anymore. Existing path segments are not changed. If your route enhancer has a requirement for the UID in the path segment like ^[a-zA-Z0-9]+-[0-9]+$, remove it. See Routes.

Removed and changed PHP API 

• InitializeControllerActionEvent and PostCheckFileReferenceEvent have been removed and the methods of PreProcessControllerActionEvent have changed. Please migrate your event listeners as described in Events.
• The event listeners AssignMediaTypeConverterEventListener and DeleteUploadedFilesEventListener and the type converter UploadMultipleFilesConverter have been removed. Logo and images use the file upload handling of Extbase.
• ClubValidator does not modify the club anymore. It validates the addresses only. Addresses without an address type are removed from the request in ManagementController before the property mapping.
• Club::getOriginalLogo() and Club::getOriginalImages() have been removed. Club::getLogo() and Club::getImages() return the ObjectStorage now.
• Club::setDistrict() accepts null to remove the district.
• ClubPagination does not read the arguments from the global request anymore. The constructor has a second argument for the arguments of the current plugin request: __construct(PaginatorInterface $paginator, array $pluginArguments = []) . The public methods getPluginArguments() and getRequestFromGlobalScope() have been removed. If you create a ClubPagination in your own code, pass $request->getArguments() of the Extbase request. Otherwise the page links lose the arguments of the plugin, e.g. the search.
• The magic finder CategoryRepository::findByParent() is not used anymore and its @method annotation has been removed. Use CategoryRepository::getCategories() to get the categories of the configured root category.

Flush caches 

As many PHP classes, templates and TypoScript have changed, flush all caches in Admin Tools > Maintenance after the update.