The Administrator Template Atum

This content was generated with the assistance of AI and should be verified against the official Joomla documentation before being relied on in production.

This sub-section’s Joomla bibliography lists the reference material consulted while preparing these pages.

Atum is the template that draws the Joomla back end: the header, the sidebar menu, the dashboards, every list and edit form, and the login screen. It is an ordinary template of type template with client="administrator", so it has template styles, parameters, positions, overrides and (as this page shows) child templates, exactly like a site template. This page explains what Atum lets a site builder configure without code (colours, colour scheme, three logos), how those options reach the page, how the login screen is assembled and customised, how administrator modules and positions work, how to override administrator layouts, and how to create an administrator child template that survives updates. It was checked against the official User Guide, the Developer Manual and the Atum sources in the joomla-cms repository (branch 6.1-dev) on 2026-10-30, and describes Joomla 6.2 (current, PHP 8.3 or newer). Atum has been the default administrator template since Joomla 4.0, so the content applies to 5.4 (security fixes only) as well; where a feature arrived later, the text says so.

The audience is the site builder who brands the back end for a client, the themer who restyles it, and the administrator who decides which dashboards and warnings editors see. The tour of the interface is in Administrator tour, dashboards and Guided Tours, the theory of styles and manifests is in Templates and template styles, child templates in general are in Child templates, and overrides in Template overrides and alternative layouts. Colour modes, right-to-left languages and the accessibility settings are in Colour modes, RTL and accessibility and the general accessibility checks are in Web accessibility; none of that is repeated here.

What Atum consists of

The manifest administrator/templates/atum/templateDetails.xml lists the files of the template:

File Purpose

index.php

The page for every administrator screen: header, sidebar, toolbar, main area.

component.php

The bare page used for modal windows and tmpl=component requests.

cpanel.php

Contains only require_once __DIR__ . '/index.php';. index.php itself detects the dashboard (control panel) screens and adapts, so there is one page for both.

login.php

The page for the login screen, described below.

error.php, error_full.php, error_login.php

Error pages for the logged-in back end, for fatal errors and for errors on the login screen.

joomla.asset.json

The Web Asset Manager registry: the style presets template.atum.ltr and template.atum.rtl, the script template.atum, the dummy asset template.active and the template.user style (user.css, weight 500).

html/

Overrides shipped with the template: layouts/status.php (the header icons) and layouts/chromes/ (body, header-item, title, well).

Its public files (compiled CSS and JavaScript, images, SCSS) are copied to media/templates/administrator/atum/. The manifest declares <inheritable>1</inheritable>, which is what allows child templates, and 12 positions: top, bottom, debug, menu, sidebar, status, title, toolbar, plus cpanel, icon, login and customtop, which components use directly and which are listed so that they show up in the position selector. Atum has no offline.php: the maintenance mode only affects the site application.

<extension type="template" client="administrator">
	<name>atum</name>
	<inheritable>1</inheritable>
	<files>
		<filename>index.php</filename>
		<filename>login.php</filename>
		<filename>joomla.asset.json</filename>
		<folder>html</folder>
	</files>
	<media destination="templates/administrator/atum" folder="media">
		<folder>css</folder>
		<folder>js</folder>
		<folder>images</folder>
		<folder>scss</folder>
	</media>
</extension>

The listing is an abridged excerpt of the real manifest (the full file also lists the error pages, the languages and the parameters).

Source: Atum templateDetails.xml in the joomla-cms repository

Administrator template styles

Atum is configured through template styles, the same mechanism as for site templates. The screens live under System > Administrator Templates (the installed templates, with the file editor and the overrides) and System > Administrator Template Styles (the styles, their parameters and the default). A fresh install has one style, Atum - Default, which is the default. Editing a style shows the Colors and Images groups of parameters and the usual assignment options. Because the administrator has no menu items, there is no per-page assignment: one style is the default for everybody, and a user can pick a different one in their own profile (Users > Manage > edit user > Basic Settings, "Backend Template Style"). Joomla reads that choice from the user parameter admin_style when it selects the template for a request, and falls back to the default style when the user has no choice or the chosen style no longer exists.

Colours

The Colors group has these parameters (names and defaults taken from the manifest):

Parameter Default Effect

hue

hsl(214,63%,20%)

A slider (the color field with format="hue"). Only the hue number (0 to 360) is used. It becomes the CSS custom property --hue, from which the SCSS derives the shades of the header, sidebar and primary buttons.

bg-light

#f0f4fb

Light background tone (--template-bg-light).

text-dark

#495057

Dark text colour (--template-text-dark).

text-light

#ffffff

Light text colour (--template-text-light).

link-color

#2a69b8

Link colour in the light scheme (--link-color, also --link-color-rgb).

link-color-dark

#6fbfdb

Link colour when the dark scheme is active.

special-color

#001B4C

Accent for special elements such as the sidebar heading (--template-special-color).

monochrome

No

A switch that adds the class monochrome to the <body>, which removes the colour from the interface (greyscale), mainly for accessibility.

colorScheme

os

0 (Disabled), os (follow the operating system), light or dark.

At render time index.php writes the values into an inline stylesheet on :root, so the same compiled CSS serves every configuration:

// administrator/templates/atum/index.php (excerpt)
$wa->usePreset('template.atum.' . ($this->direction === 'rtl' ? 'rtl' : 'ltr'))
    ->useStyle('template.active.language')
    ->useStyle('template.user')
    ->addInlineStyle(':root {
        --hue: ' . $matches[1] . ';
        --template-bg-light: ' . $this->params->get('bg-light', '#f0f4fb') . ';
        --link-color: ' . $linkColor . ';
    }');

Source: Atum index.php in the joomla-cms repository

The consequence for a themer is that the CSS variables are the supported customisation surface. Change a colour with a parameter whenever one exists, and use user.css (below) for anything the parameters do not cover. Choose colours that keep the contrast ratios of Web accessibility: the hue slider gives no warning if the header text becomes hard to read, and the monochrome switch does not fix contrast, it only removes colour. The login screen reads the same colours, but only the light values: login.php does not apply link-color-dark.

Colour scheme and personal accessibility settings

colorScheme decides whether the back end has a dark mode. With os (the default) the template follows the operating system; light and dark pin it. The attribute written on <html> is data-color-scheme-os (with the detected value stored in a cookie), or data-bs-theme and data-color-scheme set to light or dark. The switch was added in 5.1; Joomla 4.x administrators have no dark mode. Each user can override the template’s value in their own settings (the user parameter colorScheme) and a visitor-chosen value in the userColorScheme cookie takes priority over both. The same user menu also holds the accessibility settings read by index.php: a11y_mono, a11y_contrast, a11y_highlight and a11y_font, which add classes to <body> or <html>. They are personal and cannot be forced by the template style. The details of the colour-mode API are in Colour modes, RTL and accessibility.

Logos

The Images group has three logos, each with an alternative text and a checkbox that says the empty alternative text is intentional:

Parameters Where it appears Notes

loginLogo, loginLogoAlt, emptyLoginLogoAlt

The login screen, above the form.

Default media/templates/administrator/atum/images/logos/login.svg.

logoBrandLarge, logoBrandLargeAlt, emptyLogoBrandLargeAlt

The header, when the sidebar is expanded.

Default images/logos/brand-large.svg.

logoBrandSmall, logoBrandSmallAlt, emptyLogoBrandSmallAlt

The header, when the sidebar is collapsed (class logo-collapsed).

Default images/logos/brand-small.svg.

The fields are media fields (the image comes from the Media Manager and is stored as a path relative to the site root, so it must be inside the images folder). When a field is empty, the template falls back to the SVG shipped in its media folder. The alternative text logic matters for accessibility: if the text is empty and the checkbox is not ticked, the template still outputs an empty alt; the checkbox exists so that the choice is explicit. In the logged-in header the large logo is a link back to the control panel, and the link takes its accessible name from the language string TPL_ATUM_BACK_TO_CONTROL_PANEL, not from the alternative text; on the dashboard, and in edit screens that hide the menu, the logo is not a link and the configured alternative text is used.

For the Tallpine Hiking Club a good practice is an SVG for each of the three (a wide wordmark, a square mark and a login emblem) so that they stay sharp on high-density screens. The SVG upload must be allowed in the Media options first (see Media Manager), and a logo from an unknown source should be reviewed for embedded scripts before it is allowed, because an SVG is code.

Source: Joomla User Guide: Template SVG Logos (written for the Cassiopeia logo; the Atum parameters are in the manifest above)

Administrator modules and positions

The header and sidebar are not hard-coded. index.php includes modules by position:

<jdoc:include type="modules" name="customtop" style="none" />
<jdoc:include type="modules" name="title" />
<jdoc:include type="modules" name="menu" style="none" />

and layouts/status.php collects the modules of the status position into the header icons. Administrator modules are managed at Content > Administrator Modules (the User Guide page "Administrator Modules"), have a position, an access level and an optional language, and are of types that exist only for the administrator application: Administrator Menu, Administrator Dashboard Menu, Quick Icons, Logged-in Users, Popular Articles, Articles - Latest, Action Logs - Latest, Joomla! Version Information, Login Form, Login Support Information, Messages, Multilingual Status, Post Installation Messages, Privacy Dashboard, Privacy Status Check, Sample Data, Statistics, Title, Toolbar, User Menu, Feed Display, Frontend Link and Custom. The User Guide describes the positions: menu is the left sidebar, status the right-aligned icons in the banner, toolbar is above the content of list and edit screens but not on dashboards, top is below the toolbar and above the system messages, bottom below the component output, debug below everything, and customtop above the banner, which suits a site-wide warning.

A practical example for the club’s administrators is a Custom module in the position customtop that warns editors that trail reports are published after review. It needs no code:

  1. Open Content > Administrator Modules and choose New, then Custom.

  2. Enter the title, the message and the position customtop.

  3. In the Advanced tab put alert alert-warning text-center in the module class, which uses Bootstrap’s classes.

  4. Set the access level and save; the module appears on the screens of the administrator.

Remove only what you understand. The Administrator Menu module in the menu position renders the sidebar, so unpublishing it leaves a back end with no navigation, and the Login Form module (mod_login) is the way to log in; the User Guide says it should not be unpublished. If a mistake locks you out of the interface, a module can be republished by setting published back to 1 in the #__modules table, or you can create a replacement over the database. The access levels of administrator modules matter: a module visible to Public shows on the login page too, which is useful for a notice and dangerous for anything that exposes information.

Source: Joomla User Guide: Administrator Modules

The login screen

The login screen is rendered by login.php, a separate entry file. Joomla uses it when the request is the administrator login component and the user is not authenticated; the file is a small page with a header, a centred login box and a sidebar. What it contains, from the source:

  • the same two brand logos as the header, taken from logoBrandLarge and logoBrandSmall;

  • the login logo (loginLogo) above the form;

  • a visually hidden heading TPL_ATUM_BACKEND_LOGIN for screen readers;

  • <jdoc:include type="message" />, so that failed logins and logout notices appear;

  • <jdoc:include type="component" />, which prints the com_login view;

  • an <aside> that prints the site name ($app->get('sitename')) and the modules of the sidebar position;

  • the debug position.

The com_login view decides what the form box contains. Its layout (administrator/components/com_login/tmpl/login/default.php) renders mod_login and then any other module in the position login, so a notice or a "Login Support Information" module placed in login appears below the form:

$loginmodule = \Joomla\Component\Login\Administrator\Model\LoginModel::getLoginModule('mod_login');
echo ModuleHelper::renderModule($loginmodule, ['id' => 'section-box']);

$modules = ModuleHelper::getModules('login');

foreach ($modules as $module) {
    if ($module->module != 'mod_login') {
        echo ModuleHelper::renderModule($module, ['id' => 'section-box']);
    }
}

Source: com_login login layout in the joomla-cms repository

flowchart TB R[Request to /administrator, not logged in] --> L[login.php] L --> H[Header: logoBrandLarge and logoBrandSmall] L --> C[jdoc:include component] C --> V[com_login layout default] V --> M[mod_login form] V --> P[Other modules in position login] L --> S[Sidebar: site name and modules in position sidebar] L --> G[loginLogo above the form]

The Mermaid diagram shows the flow from the request to the pieces of the page.

Customising the login screen

There are three levels, from least to most invasive:

  1. Parameters. Set loginLogo, the colours and colorScheme in the style, as above. This is supported and needs no code.

  2. Modules. Add a Custom administrator module in the position login (shown below the form) or sidebar (shown in the right-hand panel of the login page) with the club’s contact for password help. Do not put sensitive data in them: they are visible to anyone who reaches /administrator.

  3. Overrides in a child template. Copy the com_login layout or the mod_login layout to the child template’s html folder and edit it. For the Tallpine club:

<?php
// administrator/templates/atum_tallpine/html/com_login/login/default.php
defined('_JEXEC') or die;

use Joomla\CMS\Helper\ModuleHelper;
use Joomla\CMS\Language\Text;

$loginmodule = \Joomla\Component\Login\Administrator\Model\LoginModel::getLoginModule('mod_login');
echo ModuleHelper::renderModule($loginmodule, ['id' => 'section-box']);
?>
<p class="text-center small"><?php echo Text::_('TALLPINE_ADMIN_LOGIN_HINT'); ?></p>
<?php
foreach (ModuleHelper::getModules('login') as $module) {
    if ($module->module != 'mod_login') {
        echo ModuleHelper::renderModule($module, ['id' => 'section-box']);
    }
}

Define TALLPINE_ADMIN_LOGIN_HINT in System > Language Overrides (administrator client) rather than in a core file.

Source: Joomla User Guide: Template Overrides

The login screen is the most exposed page of the site, so the security rules matter more here than elsewhere. Keep the layout intact: it must not hide the multi-factor prompt or the error messages. Do not display the Joomla or PHP version, a user list or an administrator hint on it. Do not print the real administrator URL as a link on the public site. A custom logo must be a file you control. For protection beyond styling (MFA, passkeys, a second path, rate limits) see Security hardening, MFA and passkeys. The login page also has password recovery pages, covered by the User Guide pages "Admin Password Recovery" and "Login and Logout Redirects".

Administrator overrides

An administrator override works the same way as a site override: a file in the template’s html folder replaces the original with the same name. For Atum the folder is administrator/templates/atum/html/; for a child it is the child’s own folder. The Templates manager (System > Administrator Templates, then Customise next to the template) has the Create Overrides tab, listing the components, modules, plugins and layouts of the administrator that can be overridden and creating the file for you. The rules are:

  • components: html/com_x/<view>/<file>.php, for example html/com_login/login/default.php (verified above);

  • modules: html/mod_x/<file>.php;

  • layouts: html/layouts/joomla/..., the same path as under layouts/ or administrator/layouts/;

  • module chromes: html/layouts/chromes/<name>.php; Atum itself ships body, header-item, title and well there;

  • alternative layouts chosen per module work for administrator modules too (the Advanced tab).

The same warnings as for the site apply: an override replaces a file, so when Joomla changes the original in an update the override keeps the old version. Compare each override with the new core file after every update (the Templates manager can show which files changed), and treat an override of the edit forms as a maintenance cost, because the forms change between minor releases. Mistakes in an administrator override can break the whole back end, so keep a way to disable it: rename the file by FTP, or set the style of your account to Atum (the admin_style user parameter), then fix the child. Never edit administrator/templates/atum itself: the update replaces it.

Administrator child templates

Child templates are supported for the administrator. The evidence is in the source: Atum’s manifest sets <inheritable>1</inheritable>, the Template view shows the Create Child Template button when inheritable is 1, and TemplateModel::child() builds the folders from the client of the parent (administrator/templates/... and media/templates/administrator/...). The method is marked @since 4.1.0, the release that introduced child templates. The Developer Manual and User Guide pages on child templates are written for the site template; Atum is treated the same way by the code.

To create the child:

  1. Open System > Administrator Templates and click Atum Details and Files.

  2. Click Create Child Template, enter tallpine and confirm. The new template is named atum_tallpine.

  3. Optionally select the existing style(s) to copy to the child.

  4. Open System > Administrator Template Styles, edit the new style (the title is built from the child and parent names), set the colours and logos, and make it the default or assign it to your account only while testing.

The generated templateDetails.xml copies the parent’s, removes the files, media, languages, update sections and inheritable, adds a files section with only the manifest and the html folder, a media section with the folders css, js, images and scss, and the parent element. A hand-written equivalent for the club is:

<?xml version="1.0" encoding="UTF-8"?>
<extension type="template" client="administrator">
	<name>atum_tallpine</name>
	<version>1.0.0</version>
	<author>Tallpine Hiking Club</author>
	<description>Tallpine branding for the Atum administrator template.</description>
	<inheritable>0</inheritable>
	<parent>atum</parent>
	<files>
		<filename>templateDetails.xml</filename>
		<folder>html</folder>
	</files>
	<media destination="templates/administrator/atum_tallpine" folder="media">
		<folder>css</folder>
		<folder>js</folder>
		<folder>images</folder>
		<folder>scss</folder>
	</media>
</extension>

Source: TemplateModel::child() in the joomla-cms repository

The child inherits the parameters of the parent’s config section, the positions, the joomla.asset.json assets and the entry files, so login.php and index.php come from Atum unless the child provides its own. Files go in:

administrator/templates/atum_tallpine/
  templateDetails.xml
  html/com_login/login/default.php
media/templates/administrator/atum_tallpine/
  css/user.css
  images/logos/tallpine-login.svg

user.css is loaded through the asset template.user (Atum’s joomla.asset.json registers user.css with weight 500 and the dependencies template.active and template.active.language, so it loads after the template CSS). A child adds a few Tallpine rules there without copying any of Atum’s CSS:

/* media/templates/administrator/atum_tallpine/css/user.css */
.login .main-brand img {
  max-width: 14rem;
  height: auto;
}

#main-brand .h1 {
  font-weight: 600;
}

Source: Joomla Manual: Web Asset Manager

The selectors come from login.php (.login, .main-brand, #main-brand). For colours, set the style’s parameters instead of overriding the variables in user.css: the inline :root block is written by the template and its order relative to the stylesheet is not something to rely on. Language strings follow the usual rules (language overrides, or the child’s own language folder if you declare one in languages). An administrator child can be installed on another site only as a package you build yourself; the Templates manager creates it in place and nothing else in the back end copies it. Back up the two folders and the style row, or keep them in the club’s Git repository. The general mechanics (lookup order, parent selection, media) are the same as in Child templates.

Security considerations

  • Administrator templates run with the highest privileges of the site. Only super users should have the core.edit permission in System > Administrator Templates, because the file editor can write PHP into the back end. Disable the editor in production if you deploy by Git.

  • Never trust the content of a logo file or of an override that you did not write. SVG can carry scripts.

  • Keep administrator modules free of private data on the login screen (position login, sidebar and customtop can be visible before authentication when the module access is Public).

  • Do not remove the MFA prompt, error messages or mod_login from your override of the login layout.

  • An override of an administrator layout that handles forms must keep the form token field; omitting it makes the form fail the CSRF check.

Common errors and pitfalls

  • Editing Atum in place. The next update overwrites administrator/templates/atum and media/templates/administrator/atum. Use a child template and the style parameters.

  • Colour changes that do not appear. The compiled CSS is cached by the browser. Hard refresh or clear the cache; if you changed user.css in a child template, check that the style assigned to your user is the child’s.

  • An unreadable header after choosing a hue. Check the contrast; use the monochrome switch only as an accessibility option, not as a fix.

  • A blank back end after an override. A PHP error in html/.... Rename the file, or switch your account’s style to the parent.

  • Logo does not show. The path is relative to the site root, so a file moved out of images disappears; SVG upload may be disallowed in the Media options.

  • Dark mode not visible. colorScheme is 0, or the user’s own setting or cookie wins over the style.

  • No Create Child Template button. The button shows only for templates with inheritable set to 1; a child cannot have a child.

  • Missing sidebar after a module cleanup. The Administrator Menu module in position menu was unpublished.

Version notes

  • 4.0: Atum introduced, replacing Isis; Bootstrap 5; the hue, colours and logos parameters.

  • 4.1: child templates in the Templates manager (child() is @since 4.1.0), which Atum supports through inheritable.

  • 5.1: the colour scheme switch (colorScheme) and the dark mode in the administrator.

  • 6.x: the entry files and the joomla.asset.json structure described here are those of the 6.1 development branch at the check date. The legacy J* aliases are off by default on new 6.x installs, so overrides written with JText or JHtml need the namespaced classes (Joomla\CMS\Language\Text, Joomla\CMS\HTML\HTMLHelper).

Corrections to older books and tutorials

  • Joomla! 4 Masterclass (Marzo, 2023) presents Atum and the child template workflow for Joomla 4.x. Joomla 4 reached its end of life in October 2025; the colour scheme switch, the dark mode and Joomla 6 are not covered. Child templates are not "brand-new" any more, and the older links to docs.joomla.org (J4.x pages) and launch.joomla.org have been replaced by the User Guide and the Developer Manual.

  • Developing Extensions for Joomla! 5 (Cámara Mora, 2023) mentions overrides and child templates for the site template; the same override rules apply to the administrator, as shown here.

  • Older tutorials describe Isis (Joomla 3) with a four-colour interface and a control panel as one screen. None of that applies to Atum.

  • Advice that Atum "cannot have child templates" is wrong for 4.1 and later: the template is marked inheritable.

References