Upgrade Guide

This guide lists the changes to check when upgrading from an earlier version of the plugin.

Upgrading to v2.0.0

Version 2.0.0 needs October CMS 4.4 or later and PHP 8.2 or later. Its composer.json file requires "php": ">=8.2" and "october/rain": ">=4.4", so Composer keeps older sites, including those on October CMS 3.6, on version 1.2. A site that upgrades from version 1.1 or earlier also needs the steps under Upgrading to v1.2.0 below.

The update runs updates/migrate_v2_0_0.php, which fills in the descriptions of the plugin's mail templates where they are empty, and records the new names of the plugin's migration files in its update history. Check these changes on each site.

• Theme layout. The default partials now use AJAX forms with inline errors, so add {% framework extras %} to the layout of each support page. AJAX Framework explains what still works with the plain {% framework %} tag or with no tag at all.
• Default look. The default partials no longer use Bootstrap classes, inline jQuery or an icon font, so pages that render them look different. Restyle them with the --support-* custom properties. Theme copies of the partials keep working, because the partial names, the variables passed to them, the handler names and paginationUrl are unchanged. They still load frontend.css, so markup they share with the defaults, such as the conversation and the ticket list marker, takes on the new styles.
• Translation. The default partials print their text with the __() function, so translate it in your theme's lang files, as Translating Text describes. The plugin's lang/en/lang.php file keeps its four keys, so themes that use them keep working.
• Mail templates. Templates that you have not customized use the new text and layouts straight away. Templates customized in the admin panel keep their own text and layout, and the update only fills in their description when it is empty. To take the new version of a customized template, open it by selecting Mail > Mail Templates from the settings menu and click Reset to Default (Delete on October CMS v4.4.0), which discards your changes.
• Subclasses. Many methods now declare return types, including public and protected model methods such as closeByUser(): bool and listParticipants(): Collection, and the SupportWorker methods. A class that overrides one of them must declare the same return type, or PHP stops with a fatal error when it loads the class. The components also replace getPropertyOptions() with one options method per property, such as getTicketPageOptions().

The admin panel pages need no action. They now use Phosphor icons, the bulk actions in the ticket list stay disabled until a ticket is checked, and internal messages have their own style. Dates follow each administrator's timezone, and the ticket page keeps loading new messages while an administrator is idle, pausing only while its browser tab is hidden.

Upgrading to v1.2.0

The update runs updates/migrate_v1_2_0.php, which widens the content and user ID columns and renders every stored message again with safe Markdown, so HTML that people typed into messages now shows as plain text. Customized copies of the templates need these changes by hand.

• Mail templates customized in the admin panel. RainLab.User v3 has no name attribute, so change user.name to user.full_name. In a subject line, print it with |raw as the default templates do, so that names such as O'Brien are not HTML-escaped.
• Theme copies of the component partials. Change ticket.user.name to ticket.user.full_name in copies of ticket-content.htm and ticket-messages.htm. In ticket-messages.htm, replace {% for message in ticket.messages if not message.is_internal %} with {% for message in ticket.messages|filter(m => not m.is_internal) %}, because Twig 3 removed the for ... if syntax and the ticket page fails with a syntax error.

Theme copies keep working without the new ticket.closed_at checks, because the components now refuse replies and edits on closed tickets themselves, but copying the checks hides Edit links that would otherwise fail.

The other changes in this release need no action.

• Uploads follow the attachment rules, which allow at most 5 files of 10 MB each by default.
• Deleting a single message needs the Delete tickets permission, as deleting a ticket does.
• Closed tickets refuse replies, edits and attachment changes until staff reopen them.
• Subjects are limited to 255 characters and messages to 50,000, and these errors reach users as validation messages.
• A forced ticket type is now saved with the ticket. Tickets submitted on such pages before this release keep an empty type.
• Tickets move to the remaining account when RainLab.User 3.5 or later merges two accounts.

For examples of the component markup, see the Creating a Helpdesk tutorial in the user guide.