Administrator Tour: Dashboards and Guided Tours

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.

This page describes the Joomla administrator interface as it was on 2026-10-30, the date on which its facts were checked against the official documentation. It was written against Joomla 6.2.x (the current release; PHP 8.3 or later), and the screens described here are the same in the 5.4 security-only line. The Guided Tours component has been part of Joomla since 4.3, whose release announcement lists it as a feature that helps new users through administrative tasks. The Joomla! User Guide (https://guide.joomla.org/) is the end-user documentation that replaced most of the legacy wiki, and the Joomla! Developer Manual (https://manual.joomla.org/docs/) is the developer reference. Where the Manual describes a topic only briefly, this page also cites the source tree.

The running example is the Tallpine Hiking Club, a fictitious mountain club whose volunteers write trail reports. The site builder logs in to the administrator once to set the site up; the editors come back every week to publish a report. This page follows both: how the interface is organised, and how to make it teach the editors their own workflow.

Two applications, one installation

A Joomla installation contains two web applications that share the same database, the same extensions and the same user table, but have different entry points, templates and menus:

  • the site (the front end) is what visitors see. It is served from the web root, uses a site template such as Cassiopeia (see Cassiopeia and Cassiopeia Extended) and is driven by menu items;

  • the administrator (the back end) is served from the /administrator path. It uses an administrator template, Atum, and is driven by the component menu in the sidebar. Only users whose groups have the Administrator Login permission can enter it.

Every extension is installed once and can have a site half and an administrator half (a component has both, a module belongs to exactly one client, a plugin has no client at all). That is why the language files, the template styles and the module lists exist twice, once per client. The architecture is explained in Introduction and Architecture, and the way logins are secured in Security Hardening, MFA and Passkeys. Because the administrator lives at a predictable address, it is the usual target of password-guessing bots; a strong password, multi-factor authentication and, where the hosting allows it, an additional restriction in front of /administrator are the baseline. Sites that need a public registration page must still keep the administrator login separate from it.

A frequent confusion for newcomers is the two language settings and the two template style lists. The Site language, template style and modules are managed under the site client, while the Administrator ones are managed under the administrator client. Changing the administrator language therefore never changes what visitors see, and the other way round. Section The user menu and personal settings shows where each user can pick a personal administrator language and style.

The Atum administrator template

Atum is the administrator template shipped with Joomla since 4.0. It replaced the Isis template of 3.x and is responsive, uses Bootstrap 5 and is built to be accessible. Its layout is made of the same blocks on every screen:

  • the header across the top with a collapsible menu toggle, the brand logo, the page title, and on the right the status icons and the user menu;

  • the sidebar (the administrator menu) on the left, with the menu groups Content, Menus, Components, Users and System, a Help entry, and a link to the front end of the site;

  • the toolbar above the main content on list and edit screens, with the buttons that act on the screen (New, Edit, Save, Options, Help);

  • the main area, which shows either a dashboard, a list or a form.

The sidebar and the header are not hard-coded. They are rendered from administrator modules assigned to template positions, so a site builder can add, remove or reorder what they show. Atum declares these positions in its templateDetails.xml: top, bottom, debug, menu, sidebar, status, title, toolbar, cpanel, icon, login and customtop. The User Guide describes them as follows: menu is the left sidebar, status holds the right-aligned icons in the banner, toolbar is shown above the content of list and edit screens but not on dashboards, top sits below the toolbar and above the system messages, bottom is below the component output, debug is below everything, and customtop sits above the banner and suits site-wide warnings.

Administrator modules are managed under Content → Administrator Modules. Among the module types the User Guide lists are Administrator Menu, Administrator Dashboard Menu, Quick Icons, Logged-in Users, Popular Articles, Articles - Latest, Action Logs - Latest, Joomla! Version Information, Post Installation Messages, Privacy Dashboard, Privacy Status Check, Sample Data, Statistics, Messages, Multilingual Status, Frontend Link, Title, Toolbar, User Menu, Feed Display and Custom. Which of them appear on a dashboard is therefore a configuration choice, not a fixed feature.

flowchart TB subgraph Atum[Atum administrator template] H[Header: status, title, user menu] S[Sidebar: position menu] T[Toolbar: position toolbar] M[Main area] end M --> D[Dashboard: modules in position cpanel and cpanel-name] M --> L[List and edit screens of a component] D --> Q[Quick icons in position icon] H --> U[User menu module]

Colour handling is a template style setting. Atum’s parameters, defined in its templateDetails.xml, include a hue and a set of colours for backgrounds, text and links, a monochrome switch, three logos (login, large brand and small brand, each with an alt text and a checkbox to leave the alt text empty on purpose) and a colorScheme list with the values Disabled, Follow the operating system (the default, value os), Light and Dark. This is how dark mode works in the administrator: with the default, the interface follows the colour mode of the visitor’s operating system or browser, and a site builder can pin it to light or dark. The full template-style workflow, overrides and the colour-mode details are in The Administrator Template Atum and Colour Modes, RTL and Accessibility. Changing the administrator logo from the style is the supported way to brand the back end for a client; editing core files is not, because the next update overwrites them.

Dashboards

A dashboard is an administrator page made of modules arranged in panels. It gives quick access to a part of the site management or shows information that is awkward to find elsewhere. Most panels duplicate a link from the sidebar, which is deliberate: the dashboards let an occasional user find a task without knowing which menu group holds it. The User Guide describes seven of them.

Dashboard What it shows

Home

The page shown after login. Its panels are instances of the Quick Icons module, plus information modules such as logged-in users, popular and recently added articles, the Joomla version, notifications about updates, sample data, privacy status and the latest actions. The Welcome tour is offered here.

Content

One panel per entry of the Content menu, and extras such as popular and recently added articles.

Menu

A panel for Menus and Menu Items, and a panel listing the items of each site menu.

Components

A panel of sub-menu links for each installed component, so a new component such as com_tallpine appears here without any extra work.

Users

A panel per group of the Users menu, and a view of who is logged in. Privacy, User Actions Log and Messaging have dashboards of their own.

System

The administrative tasks, grouped in eight panels: Setup, Install, Templates, Maintenance, Manage, Information, Update and User Permissions.

Help

Links to the Joomla help and support resources. Every panel except Joomla Help opens an external Joomla site; the Joomla Help panel opens an internal page that links to the help screens of the toolbar.

Except for Home, which opens at login, a dashboard is opened with the small dashboard icon beside its main menu item (Content, Menus, Components, Users or System). Help is a separate dashboard: the User Guide notes that its screen is not titled "Dashboard" but has all the features of the others.

How a dashboard is built

The dashboards are served by the com_cpanel component. Its view reads a dashboard request parameter. In the current source the position is computed from it: with no parameter the home dashboard uses the module position cpanel, and with a parameter the position becomes cpanel- followed by the URL-safe name, so dashboard=system loads the modules of position cpanel-system. Quick icons follow the same pattern: icon for Home and icon- followed by the name for the others. The core dashboards get fixed icons (icon-puzzle-piece for Components, icon-wrench for System and icon-info-circle for Help); a component can supply its own title and icon through a dashboard entry in its manifest, and otherwise language keys derived from the component and section name are used, falling back to the generic title. Every dashboard shows the same help screen, screen.cpanel.

This design has practical consequences for a site builder:

  • A panel is an administrator module. Open Content → Administrator Modules, filter by position, and a panel can be edited, reordered, unpublished or restricted to certain user groups. For a Home panel, use the Edit action in the panel’s top-right corner, change the Access field of the Quick Icons module and save; the panel then disappears for groups without that access level.

  • A new dashboard needs no code. Link to index.php?option=com_cpanel&view=cpanel&dashboard=tallpine, for example from a custom administrator menu item, and assign modules to the position cpanel-tallpine. The Menus section of the User Guide documents how to add a custom administrator menu.

  • The Sample Data panel and the first-install notices are best unpublished on an established production site.

The Tallpine administrator, for instance, wants the editors to land on something shorter than the full Home dashboard. A site builder can create a Trail reports dashboard with three modules in position cpanel-tallpine: a Custom module with a link to the report form, an Articles - Latest module filtered to the Trails category, and a Quick Icons module whose links open the article list pre-filtered by the Trail Warden’s access level. Because the panels are modules, the access level of each one decides who sees it, which keeps the Trail Warden group’s member-only panels away from ordinary editors.

<!-- Custom administrator module, position cpanel-tallpine, access: Editor -->
<p>Publish a new trail report in three steps.</p>
<p>
  <button type="button"
          class="btn btn-primary button-start-guidedtour"
          data-gt-uid="tallpine-editors-publish-trail-report">
    Start the "Publish a trail report" tour
  </button>
</p>

Source: Joomla Manual: Creating and launching tours

The button class and the data-gt-uid attribute are what the Guided Tours script looks for; the example module is the one the Manual itself uses to show how to launch a tour from anywhere. The module is a Custom module, so its content is filtered by the text filters configured for the author’s group (see the Text Filters section of Global Configuration). A group with the default filter strips button elements and attributes the filter does not allow, in which case the markup must be entered by a Super User or the group’s filter relaxed deliberately.

The modules themselves are covered in Modules and Positions; the only difference for the administrator is that the Site/Administrator client switch in the module manager selects the other list.

flowchart LR A[Request dashboard=tallpine] --> B[com_cpanel view reads the parameter] B --> C[Position cpanel-tallpine] B --> D[Quick icon position icon-tallpine] C --> E[Administrator modules published in that position] D --> E E --> F[Panels filtered by access level of the user]

The System dashboard

The System dashboard is where an administrator spends most of the maintenance time. Its panels group tasks that other pages of this sub-section cover in depth:

The panel names are those listed in the User Guide; individual links inside a panel vary with the installed extensions and with the permissions of the logged-in user, because a user only sees what their groups may manage. In practice an Editor who opens the System dashboard sees an almost empty page, which is the intended behaviour and not a fault.

The Help dashboard

The Help dashboard collects the places where a site builder can ask for help. Its external panels open in a new tab and point to Joomla sites such as the documentation, the forum, the extensions directory and the security pages. The internal Joomla Help panel lists the toolbar help screens. Each list and edit screen also has a Help button in its toolbar, which opens the help page for that exact screen, so an editor rarely needs the dashboard itself. For the Tallpine editors, pointing the help links at a club handbook is better done with a tour than by editing core language files.

Post-installation messages

Post-installation messages are notices addressed to the site administrator, shown after an installation or an update. They explain new features, ask for decisions (for example about the statistics collection feature that reports anonymous installation data to the project) and point to resources. The User Guide gives two examples: the statistics-collection message and a welcome message that lists helpful resources.

They are reached in two ways: from System → Information, on the Installation Messages tab, or from the button in the title bar of most list screens (it is missing on edit screens, and also if its parent module, Post Installation Messages, is unpublished). Each message is a panel with two actions:

  • Hide this message removes a message permanently. Joomla offers no screen to restore a hidden message; it can only be restored in the database.

  • Archive collapses the panel’s content and replaces the button with a green Read Again button.

Extensions can ship their own messages by adding records to the post-installation messages table from an installer script (see Installer Scripts and SQL Updates). The Tallpine package could use one to tell the administrator, after the first install of pkg_tallpine, to set the park-authority API credentials in the component options. Such a message should be short and actionable; a message that nobody can dismiss, or that repeats on every update, trains administrators to ignore all of them.

Guided Tours

Guided Tours are step-by-step walkthroughs that highlight elements of an administrator page and tell the user what to do next. They were introduced in Joomla 4.3. The User Guide describes them as a very brief introduction for complete newcomers, and ships these tours: how to create guided tours and add steps to them; "Welcome to Joomla!" on the Home dashboard; and one each for creating articles, categories, menus, tags, banners, contacts, news feeds, smart search filters and users. Several tours were refreshed in later releases, and each major or minor release can add a "What’s New" tour that appears after an update.

Starting a tour

  • The "Welcome to Joomla!" tour starts by itself the very first time a user logs in to the administrator.

  • Any other tour is chosen from the Guided Tours dropdown in the title bar of dashboards and list screens. The dropdown lists first the tours whose component selector matches the current page, and tours set to All last.

  • A tour with Auto Start switched on starts when a user reaches the screen it belongs to. A user can hide a tour permanently, and a cancelled tour waits before it runs again. The wait defaults to one hour and is set in the component’s options (the field is called delayed_time; a separate switch, allowTourAutoStart, turns auto start on or off for the whole site).

  • A button with the class button-start-guidedtour and a data-gt-uid attribute holding the tour identifier starts that tour from any page, as in the dashboard module above.

Managing tours

Tours are managed under System → Manage → Guided Tours, which is the com_guidedtours component. The list has the usual Joomla filters (status, access level, language and search), and an Options button opens the component’s permissions, so that the right to create and edit tours can be given to a group without making it a Super User. A tour has these properties, taken from the component’s form definition:

Field Meaning

title

Required. Either plain text or a language key; when it is a key, a read-only translation field shows the text for the user’s language.

uid

The tour identifier. It is suggested on Save or Save as Copy. It distinguishes tours of different origin, names the language files and is what data-gt-uid refers to. The Manual suggests the form authorname-companyname-domain-tourname.

description

The text shown at the start of the tour; HTML, or a language key.

url

Required. The relative path where the tour starts, for example administrator/index.php?option=com_content&view=articles.

extensions

Required, multiple. The component selector: the pages that offer the tour first. The Manual advises against leaving it on All, and third-party developers should select their own extensions.

autostart

Switch, off by default.

published, access, language, note

The usual status (published, unpublished, archived, trashed), access level, language (default All) and an internal note of up to 255 characters.

A tour can be duplicated, exported and imported; the export offers a SQL + INI Export, which produces the SQL statements and the language keys needed to ship the tour with an extension or with core.

Steps

Each tour has an ordered list of steps, edited from the Steps button of the tour. A step has these properties, taken from the step form definition:

Field Meaning

title, description

The heading, usually a call to action, and the help text. Both can be language keys.

target

A CSS selector for the element to highlight. Several comma-separated selectors may be given, and the first valid one is used; if none is found the step is shown in the centre of the screen.

position

Where the step bubble appears relative to the target: bottom, center, left, right or top. The default is center.

type

Next (0) moves on; Redirect (1) sends the user to another page, given in url as a relative path; Interactive (2) requires the user to act.

interactive_type

For an interactive step: form submit (1), text field (2), button (4), checkbox or radio (5), select list (6) or other (3). Text fields, checkboxes and select lists can be marked required, and a text field or select list can demand a specific required value, so the user cannot continue until the field is filled in correctly.

Interactive steps are what make a tour more than a slideshow: the user is led to type a title, tick a box or press the Save button, and the tour moves forward only when that happens. They are also the part most likely to break when the interface changes, because the selector in target must still match. Prefer stable selectors such as element IDs and name attributes over positional ones like :nth-child, and re-run every custom tour after a Joomla update. Joomla’s own tours are re-checked at each release for that reason.

A custom tour for the Tallpine editors

The Tallpine editors need to learn one task: publishing a trail report. The tour below is set up from the Guided Tours screen with these values.

Setting Value

Title

COM_GUIDEDTOURS_TOUR_TALLPINE_PUBLISH_TRAIL_REPORT_TITLE (a language key)

Identifier (uid)

tallpine-editors-publish-trail-report

Relative URL

administrator/index.php?option=com_content&view=articles

Component selector

Articles

Auto Start

No (editors start it from the dashboard button)

Access

Editor (so authors and the public never see it)

The steps are:

  1. Next, target .button-new, position bottom: "Press New to start a trail report."

  2. Redirect, URL administrator/index.php?option=com_content&task=article.add: opens the article form.

  3. Interactive, text field, required, target #jform_title, position bottom: "Give the report a clear name, such as the trail and the date."

  4. Next, target the category field, position right: "Choose Trails then Alpine or Valley, or News."

  5. Interactive, button, target the Save & Close button of the toolbar: "Save the report. A reviewer publishes it."

Target selectors depend on the markup of the form, and the editor field IDs in particular can differ between forms and releases, so confirm each one with the browser’s developer tools before saving the tour. Titles and descriptions are written as language keys so that the German edition of the site gets a German tour. The tour uses two language files, named after the identifier with dashes turned into underscores: one for the tour’s title and description and one for its steps. Every key in them must contain GUIDEDTOUR.

; administrator/language/en-GB/guidedtours.tallpine_editors_publish_trail_report.ini
COM_GUIDEDTOURS_TOUR_TALLPINE_PUBLISH_TRAIL_REPORT_TITLE="Publish a trail report"
COM_GUIDEDTOURS_TOUR_TALLPINE_PUBLISH_TRAIL_REPORT_DESCRIPTION="<p>Learn how to publish a trail report for the Tallpine Hiking Club in five steps.</p>"
; administrator/language/en-GB/guidedtours.tallpine_editors_publish_trail_report_steps.ini
COM_GUIDEDTOURS_TOUR_TALLPINE_PUBLISH_TRAIL_REPORT_STEP_NEW_TITLE="Create a report"
COM_GUIDEDTOURS_TOUR_TALLPINE_PUBLISH_TRAIL_REPORT_STEP_NEW_DESCRIPTION="<p>Press <strong>New</strong> to start a trail report.</p>"
COM_GUIDEDTOURS_TOUR_TALLPINE_PUBLISH_TRAIL_REPORT_STEP_TITLE_TITLE="Name the report"
COM_GUIDEDTOURS_TOUR_TALLPINE_PUBLISH_TRAIL_REPORT_STEP_TITLE_DESCRIPTION="<p>Use the trail and the date, for example <em>Alpine ridge, 12 July</em>.</p>"

Source: Joomla Manual: Creating and launching tours

The Manual describes the same two-file convention for the core tour joomla-welcome, whose files are guidedtours.joomla_welcome.ini and guidedtours.joomla_welcome_steps.ini. The exact key names above are an organisational choice; the rule is the GUIDEDTOUR substring.

There are two ways to deliver the tour:

  • By hand, for one site. Create it in the interface, choose Export and keep the file in the repository, so that the staging and production sites receive the same tour.

  • With an extension. A tour that belongs to an extension can keep its language files inside the extension, provided its uid starts with the extension type and name: com_, mod_, plg_[group]_ or tpl_ followed by the name, for example com_tallpine.publish-trail-report. The extension’s installer script or SQL update file inserts the rows. The core "What’s New" tours are delivered the same way through SQL update files in com_admin, and the Manual shows that a new major version removes earlier "What’s New" tours with explicit statements on the #__guidedtours and #__guidedtour_steps tables, and disables the autostart of the previous minor’s tour with an UPDATE. It recommends listing the identifiers with IN (...) rather than LIKE, so that tours created by users are never deleted by accident. Images used in a tour come from the /images folder, or, for an extension, from a path starting with media/.

-- Remove the previous release's tour when Tallpine 2.0 ships (MySQL)
DELETE FROM `#__guidedtour_steps`
 WHERE `tour_id` IN (SELECT `id` FROM `#__guidedtours`
                      WHERE `uid` IN ('com_tallpine.whatsnew-1-0'));
DELETE FROM `#__guidedtours` WHERE `uid` IN ('com_tallpine.whatsnew-1-0');

Source: Joomla Manual: Create a What’s New tour

PostgreSQL needs its own file with double-quoted identifiers; the query builder does not make raw install SQL portable between the two databases (see Installer Scripts and SQL Updates).

sequenceDiagram participant E as Editor participant D as Dashboard module participant G as Guided Tours script participant A as Administrator page E->>D: Press button-start-guidedtour D->>G: data-gt-uid = tallpine-editors-publish-trail-report G->>A: Load tour url and highlight target E->>A: Act on an interactive step A-->>G: Required field filled G->>A: Show next step or redirect

Permissions and security

Tour descriptions and step texts are HTML that every user who runs the tour will render, so edit rights on com_guidedtours are a privilege worth limiting: a person who can write a step can put markup in front of a Super User. Give the Create and Edit actions only to the group that maintains the documentation. Because the tour extensions filter limits who sees a tour on a given page and the access level limits who can run it, a tour that mentions a member-only feature, such as the Trail Warden’s condition reports, should carry the Trail Warden access level. A tour must never include real credentials as example input, and a required value must not be a secret.

Auto start is the setting most often regretted. A tour that restarts after every cancellation annoys experienced users; leave auto start off for everything except onboarding, and use the delay and the user’s hide permanently choice to stay out of the way.

The user menu and personal settings

Every administrator user has a user menu in the header, rendered by the User Menu module (position status). It gives the signed-in user access to their own account. The account form is the standard user edit screen, which carries a Basic Settings tab with three personal choices (the fields admin_style, admin_language and editor):

  • the administrator template style, so one user can use a different Atum style than the rest;

  • the administrator language, chosen from the installed administrator languages;

  • the editor, so a Tallpine author who prefers a plain textarea can have it while the rest of the club uses TinyMCE.

Each of them also accepts Use default. Setting a personal administrator language is the recommended way to give a German-speaking board member a German interface without changing the language of the site’s visitors; the language packs themselves are discussed in Language Files and Internationalisation.

Accessibility settings

The same user form has an Accessibility Settings tab. It contains four switches, each off by default, stored with the user and applied by the administrator template:

Setting Effect

Monochrome (a11y_mono)

Shows the interface without colours.

High contrast (a11y_contrast)

Increases the contrast of text and controls.

Highlight (a11y_highlight)

Emphasises links and focus so that they stand out more.

Font size (a11y_font)

Enlarges the text.

The labels shown in the interface come from the language files, so wording differs between languages. Dark mode is not one of these switches: by default it follows the operating system’s colour preference, as described above, unless the template style pins the scheme. A site builder who serves club members with visual impairments should enable these per user instead of editing the template, since the settings survive template updates. The wider accessibility story (the Accessibility Checker, the front-end template, WCAG) is in Colour Modes, RTL and Accessibility, and a general treatment of web accessibility is on the Accessibility page.

Common problems

  • The dashboard shows no panels. The modules in the cpanel or cpanel-name position are unpublished, or the user’s groups lack the module’s access level. Check Content → Administrator Modules, with the filter set to the position.

  • A tour does not start. The tour is unpublished, its access level excludes the user, its relative URL has a typo, or auto start is switched off in the component options. If the highlighted element is missing, the step falls back to the centre of the screen instead of failing, which usually points to an outdated selector.

  • The post-installation button is gone. The Post Installation Messages module is unpublished. Messages that were hidden cannot be shown again from the interface.

  • The Welcome tour is not shown to a new editor. It runs for a user’s first login to the administrator only; start it manually from the Home dashboard dropdown.

  • A Custom module button does nothing. The text filter removed the markup, or the page does not load the Guided Tours script because no tour is available on that screen.

Corrections to older material

Joomla! 4 Masterclass (Marzo, Packt, 2023) is the best book overview of the administrator screens, and its dashboard chapter still maps onto the screens above. Its target is Joomla 4.x, which reached end of life in October 2025, and it does not cover the Joomla 5 and 6 releases; it links to docs.joomla.org and launch.joomla.org pages that have been superseded by the Joomla! User Guide at guide.joomla.org. Material written for Joomla 3 describes the Isis template, the control panel as one screen and the four-colour interface; none of that applies to Atum. For the current documentation locations, and a list of older advice to avoid, see Where Older Books and Tutorials Are Outdated.

References