System Branding Developer Guide

🛠️ System → Branding — Developer Guide

System → Branding (system/branding/index.php, saved by api/system/get_branding.php / save_branding.php) holds the install-wide look: the logo, header and footer text, the start page, the sign-in screens, the Files desktop logo, and, since 3.5.0, the system name and the "Back to…" link. For the portal's own theming, see Branding the portal — Developer Guide.

Every key the page saves is owned by system / tab branding in includes/settings_keys.php.

System name (moved here in 3.5.0)

system_settings.system_name is the first part of every page title. It used to live on Tickets → Settings → General, which now only points here.

• Read: systemName() in includes/system_name.php. A blank value means Service Desk.
• Used by: pageTitle(?string $module, ?string ...$parts) builds <system name> - <module> - <page> on every analyst page (#173; see Internationalisation).
• Saved: save_branding.php writes it only when the form sends system_name, so an older client leaves it alone. The limit is 100 characters.
• Settings search: the card's heading is id="system-name", listed in systemAreaSettings() (system/includes/areas.php), so typing "name" on the System landing finds it.

The "Back to…" link (3.5.0)

A link at the top of the portal, the analyst screens or both, back to the site people reach FreeITSM from. It was proposed in PR #174.

Key	Value
back_link_label	The words, up to 60 characters.
back_link_url	http(s) only.
back_link_where	portal · analyst · both (BACK_LINK_PLACES)

All the logic is in includes/back_link.php:

• backLinkSettings($conn) returns the three settings raw, for the page.
• backLinkUrlValid($url) accepts https?:// with no spaces, quotes or angle brackets, and must also pass FILTER_VALIDATE_URL.
• backLinkHtml($conn, 'portal'|'analyst') returns the link and its small style block, or '' when the link isn't set up, isn't for this side, or its stored address isn't valid.
  • 🔴 The address is checked on save and again when drawn, so a value written some other way (SQL, an import) can never become a javascript: link in every header.
  • The output is escaped with htmlspecialchars.

It's drawn in two places:

• Analyst side: renderHeaderRight() in includes/waffle-menu.php, first in .header-right, so every module header gets it. It's wrapped in try, because the header must never fail.
• Portal: self-service/includes/header.php, before the notification bell.

On layout: the analyst navbars are full, so below 1700px the analyst link shows only the arrow (.back-link-analyst .back-link-label hidden), with the words in title and aria-label. Below 700px both sides show only the arrow.

save_branding.php validates the three fields before writing anything, because the endpoint has no transaction. Text without an address, or an address without text, is refused.

Tests

The link was checked over HTTP (9 checks), with every branding setting snapshotted and restored exactly afterwards:

• a javascript: address is refused;
• one half without the other is refused;
• the link saves and reads back;
• other settings are untouched;
• the analyst header escapes the address;
• the portal shows it;
• "portal only" leaves the analyst side alone;
• a bad stored address is never drawn.