Skip to content

Settings One Page Developer Guide

Ed Mozley edited this page Nov 20, 2026 · 2 revisions

Settings on one page - Developer Guide

GH #399 Β· 5.8.0 Β· user page: Settings on one page

In plain words

Every module settings page already drew its tab bar through one function, renderSettingsTabBar() (includes/settings_manifest.php). That function now also loads assets/js/settings-view.js, which adds the Tabs / One page switch. So 20 settings pages gained the feature by changing one PHP function and adding one script and one stylesheet - no settings page was edited.

The files

File What
🟣 includes/settings_manifest.php renderSettingsTabBar() calls the new renderSettingsViewSwitch()
🟑 assets/js/settings-view.js the switch, the index, search, warming the tabs
πŸ”΅ assets/css/settings-view.css One page layout, desktop only (min-width: 769px); colours only as var() fallbacks
🌐 lang/*/common.php common.settings_view.*, 9 languages
πŸ—„οΈ user_preferences settings_view = 'page' or '' (Tabs) - no schema change

The server side

function renderSettingsViewSwitch(): void
{
    static $done = false;
    if ($done) return;
    $done = true;
    $mode = '';
    ... SELECT preference_value FROM user_preferences WHERE analyst_id = ? AND preference_key = 'settings_view'
    $mode = (string)$st->fetchColumn() === 'page' ? 'page' : '';
    $cfg = ['mode' => $mode, 'save' => $base . 'api/system/set_user_preference.php', 'labels' => [...]];
    echo '<link rel="stylesheet" href="' . $base . 'assets/css/settings-view.css?v=1">';
    echo '<script>window.SETTINGS_VIEW = ' . json_encode($cfg, JSON_HEX_TAG | ...) . ';</script>';
    echo '<script src="' . $base . 'assets/js/settings-view.js?v=1" defer></script>';
}

Read on the server, so the page knows the person's view before the script runs. Labels come through t() and are handed over in SETTINGS_VIEW.labels, so the script needs no translation namespace of its own. Saving goes through the ordinary set_user_preference.php.

The script

Matching tabs to panels

const items = Array.from(bar.querySelectorAll('.tab[data-tab]')).map(btn => {
    const id = btn.dataset.tab;
    return {
        btn, id,
        label: btn.textContent.replace(/\s*β†—\s*$/, '').trim(),
        moved: btn.tagName === 'A',
        panel: btn.tagName === 'A' ? null
             : (document.getElementById(id + '-tab') || document.getElementById('tab-' + id) || document.getElementById(id)),
    };
});
const panels = items.filter(i => i.panel && i.panel.classList.contains('tab-content'));
if (panels.length < 2) return;

Every module uses <id>-tab for a panel except Problem Management (tab-<id>). A page whose tabs match fewer than two panels - the SSO pages draw a tab bar with no panels - is left alone. A tab that moved to another page (<a class="tab">, GH #263) becomes an outward link in the index.

Warming the tabs

Many tabs load their content when first opened (lookups, lists, the label designer). Showing their panel without opening them would show an empty box. So the first switch to One page clicks each tab once, through the page's own handler, then returns to the tab that was open:

function warm() {
    if (warmed) return;
    warmed = true;
    const wasActive = items.find(it => it.btn.classList.contains('active'));
    const url = location.href;
    panels.forEach(it => { try { it.btn.click(); } catch (e) { /* a tab that fails to open must not stop the rest */ } });
    if (wasActive) { try { wasActive.btn.click(); } catch (e) { /* ignore */ } }
    if (location.href !== url) history.replaceState(history.state, '', url);   // the tab switches may have rewritten ?tab=
}

The script is deferred and starts in a DOMContentLoaded handler plus setTimeout(0), so it runs after the page's own start-up code has registered its handlers - clicking a tab before the page set up its switcher would load nothing.

Showing everything without moving anything

Nothing is moved in the DOM. The index is inserted as the container's first child, and CSS grid places it:

body.sv-page .container { display: grid; grid-template-columns: 230px minmax(0, 1fr); column-gap: 24px; align-items: start; }
body.sv-page .container > * { grid-column: 2; }
body.sv-page .container > .sv-index { display: block; grid-column: 1; grid-row: 1 / span 999; position: sticky; top: 12px; ... }
body.sv-page .tabs { display: none; }
body.sv-page .tab-content { display: block !important; ... }
body.sv-page .tab-content.sv-hidden { display: none !important; }

Ids, page scripts and each page's own CSS keep working because every element stays where the page put it. !important is needed because each page's own tab switcher hides inactive panels.

Search and the index

Search matches a section's tab name, its text, and the values and placeholders of its inputs, and hides the rest (sv-hidden); the index dims them (sv-dim). An IntersectionObserver marks the section at the top of the screen (sv-here). Arriving with ?tab=x scrolls to that section.

Scrolling to a section - never scrollIntoView()

Some settings pages scroll the whole window (Checklists, Learning); others (Tickets) scroll inside .container under a fixed-height shell whose body is overflow: hidden. scrollIntoView() scrolls every scrollable ancestor, and a script is allowed to scroll an overflow: hidden element - so on Tickets it also scrolled the body by the header's height: the navbar vanished off the top and a gap appeared at the bottom that the person could not scroll back. Ed found it on the first day (2026-11-20). goTo() scrolls only the nearest ancestor that really scrolls, or the window:

// TRAP: never panel.scrollIntoView() here ...
function goTo(panel, smooth) {
    let el = panel.parentElement;
    while (el && el !== document.body && el !== document.documentElement) {
        const oy = getComputedStyle(el).overflowY;
        if ((oy === 'auto' || oy === 'scroll') && el.scrollHeight > el.clientHeight) break;
        el = el.parentElement;
    }
    // scroll el by the panel's offset within it, else window.scrollTo(...)
}

Checked headless on Tickets: before the fix the document scrolled 62px on load with ?tab=mailboxes; after it, the header stays at 0 and each index link lands its section 12px below the top of .container.

Phones

const phone = window.matchMedia('(max-width: 768px)');
function setMode(next, save) {
    if (phone.matches) next = 'tabs';
    ...

All One page CSS is inside @media (min-width: 769px), and the switch is hidden below it, so the phone layout is untouched (per the mobile rule: mobile must not touch desktop, nor desktop mobile).

Checked

On the test install, every module settings page in One page view: no script errors; the index lists every section (Tickets 26, Assets 19 including Intune's outward link). On Assets: 18 panels shown, a search for "label" left 2, a search matching nothing showed No settings match, switching back to Tabs showed one panel and the tab bar and saved ''. At 390px wide, with One page saved, the page stayed as tabs with no switch.

Checklists and Learning (moved onto the shared tab bar)

They used to draw their own tab bars, so they had no switch. Both now call renderSettingsTabBar():

  • Learning (lms/settings/index.php) draws its bar from lms/settings/manifest.php through settingsVisibleTabs(), with its own switcher name lmsSettingsTab. The manifest's capabilities are the same two grants the page already checked (LMS_MANAGE, LMS_TESTS), so the bar and the panels cannot disagree. ?tab= now opens a tab, as everywhere else; #tests still works.
  • Checklists (checklists/settings/index.php) passes an inline list with 'cap' => null on every tab. There is deliberately no checklists/settings/manifest.php: manifests are discovered by glob, and each one adds a module to System -> Roles. Every Checklists tab has always been open to anyone with module access; gating them is a separate decision, made by moving that list into a manifest. Panels are now <id>-tab / .tab-content, in the module's teal via --accent.

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Responses to feedback

Blue sky thinking

Bugs resolved

Pull requests

Links

Clone this wiki locally