Skip to content

System Page Layout

Ed Mozley edited this page Nov 15, 2026 · 4 revisions

📐 System page layout - Developer Guide

Since 5.3.0 · Related: UI style guide §3 Full width, Help page house style

Every System screen uses one page layout, defined once and checked in a browser. Before this, each page carried its own container and heading rules, and they had drifted:

Measured at 1600px, before
Left gutter 20, 24, 28, 32 or 40px - and 416px on Encryption and Docker (an 800px centred column)
Page title h1 or h2, 22 or 24px, weight 600 or 700, 62-98px from the top
Panels and intros capped at 720-900px on 18 pages
Height 20 pages ran 14px past the bottom of the window (sized as 100vh - 48px; the header is taller than 48px)

1. 📁 Files

File Role
assets/css/system-page.css The layout. .sys-page, .sys-page-head, .sys-title, .sys-subtitle, .sys-actions, .sys-panel, and the desktop height rule
system/includes/header.php Loads it - so every System page has it without its <head> remembering, and after the page's own <style>, so it wins a tie
tests/system-page-layout.php Opens every System screen in headless Chrome and measures it (§4)

2. 🧱 The markup

<div class="xx-container sys-page">              <!-- the page's content box -->
  <div class="sys-page-head">
    <div>
      <h1 class="sys-title">Cost Centres</h1>
      <p class="sys-subtitle">What this page is for.</p>
    </div>
    <div class="sys-actions"> <!-- optional: primary buttons, on the right -->
      <button class="btn btn-primary">Add</button>
    </div>
  </div>
  <div class="sys-panel"> ... </div>              <!-- optional white card -->
</div>
  • A page keeps its own class on the content box (.cc-container) as well as sys-page, so its own rules for things inside it - and mobile.css's rules for it - still apply. Only width, margin, padding and the title rules move to the shared file.
  • A back link or breadcrumb stays above .sys-page-head.

3. 🔑 The rules it enforces

  • Full width, one gutter. .sys-page is width: 100%; max-width: none; margin: 0; padding: 24px 32px 40px (16px on a phone).
  • One title. 22px, weight 700 (19px on a phone).
  • No cap of your own. ⚠️ This is the one that keeps coming back: a "tasteful" 760px reading measure on a panel or an intro is still a cap (it bit System → Search, Tickets → Indexing, Forms → Collections and System → Locations). Caps belong only on controls: a search box, a single input or select, a form group holding one input, a table cell, an image, a modal. Anything else that genuinely needs one says so with data-sys-cap="why" - e.g. the portal mock-up on Self-service, the shared AI settings panel (includes/ai_settings_panel.php caps itself at 640px).
  • Height. On a desktop, when .sys-page is the body's own child, the body becomes a flex column: the header takes its real height and the page fills the rest and scrolls (body:has(> .sys-page)). Pages with another wrapper (a .main-container, a .settings-shell) already did this themselves. Never size a page as calc(100vh - 48px).

3a. 🪟 Dialogs (modals)

Every System dialog has the app's canonical header / body / footer look (the same as inbox.css's modal), whatever opens it. A page keeps its own overlay, its id and its open/close (.modal.active, .cc-overlay.open, [hidden] ...); the dialog box carries the classes:

<div class="xx-overlay">
  <div class="sys-modal [sys-modal-wide|sys-modal-xl]" role="dialog">
    <div class="sys-modal-head">Edit cost centre <button class="sys-modal-x">&times;</button></div>
    <div class="sys-modal-body"> fields - this part scrolls </div>
    <div class="sys-modal-foot"> Cancel  Save </div>
  </div>
</div>
  • Widths: 520px (default), 820px (sys-modal-wide, an import preview), 1000px (sys-modal-xl). Nothing in between.
  • Look: 8px corners, an 18px / 600 title 24px in, body content at least 24px from the edges, footer buttons on the right 24px in; a note on the left of the footer goes in .sys-modal-foot-left.
  • A <form> around body + footer gets .sys-modal-form, which makes it a flex column - otherwise the body never scrolls (the inbox.css trap: a plain form between the box and the body has no bounded height).
  • The new classes go alongside a page's old ones (class="cc-modal sys-modal"), so JavaScript that looks for the old ones still finds them; only the old CSS for the box, head, body and foot is deleted.
  • The Locations editor (assets/js/locations-tree.js) also runs on Assets → Settings, which does not load this file - its dialog carries both the canonical inbox.css classes and these, which describe the same look.

Before this, about 34 dialogs were built eight different ways: titles missing, 16px or 18px, 600 or 700; corners 8 or 10px; padding 18-25px or none (Edit location had its fields flush with the edge); widths from 378 to 1100px.

4. 🧪 The test

FREEITSM_TEST_DATABASE=freeitsm_prtest FREEITSM_TEST_URL=http://localhost/freeitsm-prtest php tests/system-page-layout.php
FREEITSM_SPL_ONLY=cost-centres,sso/entra.php ...   # just those

It finds the pages itself - every card in getSystemAreas() plus every other system/*/*.php and system/*/*/*.php that includes the System header - so a new page is checked the day it exists. Two levels down since 5.4.0, for the three Microsoft 365 pages in system/integrations/microsoft365/ (PR #352); a folder's own includes/ are parts, not pages, and are skipped (the Debug tools' d0NN/index.php pages do not include the header themselves, so they are not picked up). For each, at 1600px:

  1. the .sys-page fills the width it is given (the parent's inner width, scrollbar excluded);
  2. its gutter is 32px;
  3. its .sys-title sits on the gutter at 22px / 700;
  4. nothing inside is capped (a visible block 400px+ wide held narrower than the page by a max-width, controls and data-sys-cap excepted);
  5. the page ends inside the window - no second scrollbar, the bottom reachable;
  6. every dialog on the page, opened (animation off) and measured against §3a: a .sys-modal with a head and body, 520 / 820 / 1000 wide, 8px corners, the title 18px / 600 at 24px, body content 24px+ from the edges, the last footer button 24px from the right.

Pages that only open for a record get one: three temporary ZZ layout test sign-in providers (LDAP, Entra, CardDAV), removed in finally, and the first tracker in the integrations registry. Each Chrome run has its own profile, so two runs at once do not collide.

Not checked, on purpose ($APP_PAGES, with the reason printed): the Engineering Wiki and the API reference, which are document readers with their own navigation, and the help pages (system/help/, */help.php), which follow the Help page house style.

5. ✅ Adding a System page

Use the markup in §2, put no max-width on anything but a control, and run the test with FREEITSM_SPL_ONLY=<your page>. Five passes and it is done.

A new card on the System landing needs a group - see §6. php tests/system-card-groups.php fails until it has one.

6. 🗂️ The landing's card groups

(5.3.0, PR #347 by vsc55, #346; review: System cards by topic - PR review.) The landing (system/index.php) shows its cards By topic - a heading over each group - or A-Z, by translated title. Each area in getSystemAreas() (system/includes/areas.php) names its group:

[
    'icon'     => 'currencies',
    'url'      => 'currencies/',
    'group'    => 'organisation',      // a key of systemAreaGroups()
    'title'    => 'system.landing.currencies_title',
    ...
],

systemAreaGroups() lists the groups in the order they are drawn, each with its heading's translation key: start, people, signin, portal, organisation, look, integrations, health, more - and other, the catch-all for an area with no group, drawn last. Within a group the cards keep the registry's own order.

  • The order is applied in the browser. The server prints every card with data-group, data-index (its place in the registry) and data-title (its translated title), and the groups as JSON on the grid (data-groups). The script draws a .system-group-head before each group, or sorts by data-title with localeCompare for A-Z (Help & guides, data-pinned, stays first). The choice is in localStorage (system_cards_order).
  • The search hides a heading whose cards it has all hidden.
  • Nothing else changes: the cards, their links and the search haystack are the same in both orders.

The guard. php tests/system-card-groups.php - no database, no config.php - reads the registry and lang/en/system.php and fails when an area names no group, names other, or names a group whose heading has no English text. It also pins two placements decided on merge: Search under health, Currencies under organisation.

When you add a System area, give it a 'group' from systemAreaGroups(). A new group needs a key there, its heading in lang/en/system.php (system.landing.group_<key>), and its translations.

7. 🛡️ Who may open a System page - systemPageAllowed()

(5.4.0, PR #352 by vsc55, #263; review: Microsoft 365 in Integrations.) System is for administrators, with Preferences open to everyone. When Intune moved here from Assets → Settings, the asset managers who set it up there - granted by a capability, not by being an administrator - had to keep it. That is the one exception, and it is one rule:

// system/includes/page_access.php
function systemPageAllowed(PDO $conn, int $analystId, string $page, ?array $grant): bool
  1. $page === 'preferences' → allowed.
  2. analystIsAdmin() (asked of the database, not the session) → allowed.
  3. The page declared a grant, and the analyst has that module (analystCanAccessModule()) and that capability (analystHasCapability()) → allowed.
  4. Anything else, or anything that throws → refused (fails closed).

Both doors ask it. system/includes/page_gate.php and system/includes/header.php each call systemPageAllowed() with the page's $current_page and $system_page_grant, so the gate and the header can never disagree. Refused → redirected to the app's home.

A page opts in by setting the grant before the includes:

$current_page = 'integrations';
$system_page_grant = ['module' => 'assets', 'cap' => Cap::ASSETS_INTUNE];

Today exactly three pages do: system/integrations/microsoft365/index.php (which then shows a non-administrator only its Intune half), intune.php and intune_import.php.

  • The page gate is the screen, not the security. The endpoints behind a granted page must check the capability themselves - the Intune ones (api/intune/*, api/settings/*) always did. System APIs stay requireAdminJson().
  • Do not grant a page lightly. The point of System being administrators-only is that one check covers it. A new exception needs a reason as good as "these people could already do this, on a page that moved".
  • The capability still lives with its module. The Intune tab stays declared in asset-management/settings/manifest.php with 'moved_to' => 'system/integrations/microsoft365/intune.php': the manifest is what lists the capability in System → Roles and owns the intune_* setting keys. settingsMovedTo() and renderSettingsTabBar() (includes/settings_manifest.php) turn it into a link and redirect ?tab=intune; settingsFirstTabId() skips a moved tab.

The test. tests/intune-system-page.php (FREEITSM_TEST_DATABASE, and FREEITSM_TEST_URL for the HTTP part): the manifest entry and its keys, the redirect, each Intune page saving only its own keys, and who may open what - an administrator, an analyst with Assets and the Intune capability, one without the capability, one with it but without Assets, and Preferences. Over HTTP, the Intune-only analyst opens the three Microsoft 365 pages - seeing no Entra ID or Also from Microsoft - and is turned away from every other System page, and with Assets switched off the Intune pages show one line instead of a form.

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Responses to feedback

Blue sky thinking

Bugs resolved

Pull requests

Links

Clone this wiki locally