Theming

The components render default markup that needs no CSS framework, icon font or jQuery. The partials use the plugin's own classes, and attachment lists open and close with a <details> element. This article explains what the default markup needs from your layout, how to override its partials, how to restyle it and how to translate its text. To write all of the markup yourself instead, see the page of each component.

AJAX Framework

The default partials need the AJAX framework with its extras, so add this tag to the layout of each support page.

{% framework extras %}

The submit, reply and edit forms are AJAX forms, for example {{ form_ajax('onSubmitTicket', { files: true, flash: true, validate: true }) }}. With the extras loaded, the forms behave as follows.

• An error appears under its field, in an element such as <div data-validate-for="subject"></div>, and also as a flash message. The handlers report errors under subject, content, type_id and files. Every attachment error goes under files, next to the form's single <input name="files[]" type="file" multiple>.
• The submit buttons show a loading indicator while the request runs.
• After a successful save, the handler redirects, and the next page shows the success message from the flash-messages partial as a notification.

With the plain {% framework %} tag, the forms still send AJAX requests, but errors appear as browser alerts, success messages appear as a message box at the top of the component, and the buttons show no loading indicator.

Without any framework tag, each form posts the page instead, through a hidden _handler input, and errors and success messages appear as message boxes at the top of the component. The Close ticket button, the attachment Delete buttons and the ticket type select still need the AJAX framework. The submission form shows its fields only after the user picks a type, so without the framework it only works on a page that forces a type.

Stylesheet

Each component adds the plugin's assets/css/frontend.css file to the page through the layout's {% styles %} tag. Its rules apply only inside the responsiv-support element that wraps each default partial, so they do not affect the rest of your theme. Keep that wrapper in theme copies of default.htm.

Custom Properties

To restyle the partials, set these custom properties in your theme's stylesheet, on .responsiv-support or on an ancestor such as :root.

For example, the following changes the accent and highlight colors and removes the rounded corners.

.responsiv-support {
    --support-accent: #4f46e5;
    --support-highlight: #db2777;
    --support-radius: 0;
}

The muted, border, surface and bubble defaults mix the text color, so they suit light and dark themes. The danger, success and warning defaults use light-dark(), which picks its dark value only when the page sets a dark color-scheme.

Classes

The partials use these classes, which your theme can also style.

• Forms: support-form, support-field, support-label, support-input, support-check, support-help, support-error and support-actions.
• Buttons: support-button, support-button-primary, support-button-danger and support-link-button.
• Page parts: support-notice, support-panel, support-flash with support-flash-{type}, support-header, support-title, support-table and support-empty.
• Pager: support-pager, whose items take is-active, is-disabled, pager-gap, pager-previous and pager-next.

The conversation keeps the classes of earlier versions. Each message is a message-container inside ticket-conversation, where the user's messages add active-user and staff messages add staff. In the ticket list, the ticket-indicator marker adds has-new when the ticket has a staff reply to read.

Overriding Partials

Each component renders its default partial, which renders the others. To change one part of the markup, copy that partial from the plugin into a folder named after the component alias in your theme's partials directory. For example, to change how the conversation renders, copy components/ticket/ticket-messages.htm to partials/supportTicket/ticket-messages.htm. The other parts keep using the plugin's partials.

The components/partials folder holds the flash-messages, message-attachments and pagination-list partials, which the components share. Override them in the folder of each component that uses them, for example partials/supportTicket/flash-messages.htm.

When the page gives the component another alias, for example [supportTicket ticket], the folder follows that alias, which here is partials/ticket. See Overriding Component Partials for more details.

When copying a partial, keep these parts of its markup.

• The responsiv-support wrapper in default.htm, which the stylesheet needs.
• The partialMessageForm and partialUpdateAttachments element IDs, which the AJAX handlers update.
• The hidden _handler inputs, so that the forms still work without the AJAX framework.
• The message-{id} anchor on each message in ticket-messages.htm, which mail links and the update page return to.

A theme copy does not receive the changes of plugin updates, so compare it with the plugin's version after updating.

Translating Text

The default partials, and the error and success messages of the handlers, print their text with the __() function, for example {{ __('Submit ticket') }}. October CMS reads the JSON lang files of a plugin only in the admin panel, so the plugin's lang/en.json file, which lists every string, has no effect on your site. Translate the strings in your theme's lang files instead. See Theme Localization.

For example, add the strings to the lang/fr.json file of your theme, using the English text as the key.

{
    "Submit a new ticket": "Soumettre un nouveau ticket",
    "Submit ticket": "Envoyer le ticket",
    "This ticket has been closed.": "Ce ticket a été fermé."
}

The theme:scan command only scans the theme's own templates. It finds the strings of partials that you have copied into the theme, but not those of the plugin's partials and handlers, so copy those keys from the plugin's lang/en.json file.