Guided Tours in Joomla

2. Anatomy of a Tour and a Step

Before building anything, it helps to know every field, because each one maps directly to a database column you may meet later.

2.1 The Fields of a Tour

2.2 The Fields of a Step

A step always belongs to one tour through its tour_id, and its place in the sequence comes from the ordering value you set by dragging rows in the steps list.

4. Step Types and Interactive Steps

Every step has a type that decides how the user moves forward. Joomla stores it as a small integer, and the three values are fixed in the component.

4.1 The Three Step Types

Use Next for "look at this" steps. Use Redirect when a tour spans more than one screen, for example moving from the article list to the article edit form. Use Interactive when you want a hands-on tutorial where the user types, clicks, or selects something themselves.

4.2 The Interactive Types

When a step is interactive, a second field, Interactive Type, says exactly what the user must do. Joomla defines six of them:

For a Text Field or Select step you can set a required value in the step's parameters. The tour then waits until the user enters or selects exactly that value before the Next button unlocks. This is how a tour can guide someone through filling a form correctly, not just reading about it.

6. Autostart and User State

Tours can start by themselves, but only once. Joomla remembers what each user did so a tour does not nag them forever. This is the trickiest part of the feature, so it is worth understanding.

6.1 The Autostart Flag

If a tour has Autostart on, Joomla looks for it when the user reaches the matching screen. If the user has not seen it yet, it starts automatically. There is also a global switch under Users → Guided Tours → Options called Allow Tour Auto Start; turn it off and no tour auto-starts anywhere, regardless of the per-tour flag.

6.2 The Three States

When a user finishes or stops an auto-starting tour, Joomla records one of three states in their user profile:

The "while" for a delayed tour comes from the Delayed Time option, which defaults to 60 minutes. After that period the tour can auto-start again, which is handy for a user who closed it because they were busy, not because they were finished.

6.3 Where the State Lives

The state is saved per user in the #__user_profiles table, under a key like guidedtour.id.5 for the tour with id 5. Because it is stored against the user, a tour you completed will not bother you again, but a brand new editor still sees it fresh. If you want to test autostart repeatedly, delete that profile row for your account, or test with a different user.

8. Under the Hood (Developer View)

Now the technical layer. Guided Tours is a clean example of a modern Joomla component plus a system plugin, and it is small enough to read in an afternoon.

8.1 The Two Tables

Everything lives in two database tables:

#__guidedtours        one row per tour
#__guidedtour_steps   one row per step, linked by tour_id

The key columns of #__guidedtours:

id           primary key
title        tour title (or a language key)
uid          unique text identifier, e.g. joomla-guidedtours
description  intro popover HTML (or a language key)
url          relative URL of the page the tour runs on
extensions   JSON list of components, e.g. ["com_content"]
autostart    0 or 1
access       viewing access level
language     language tag or *
published    publish state

The key columns of #__guidedtour_steps:

id                primary key
tour_id           the parent tour
title             popover heading
description       popover body HTML
position          top / bottom / left / right / center
target            CSS selector of the highlighted element
type              0 = next, 1 = redirect, 2 = interactive
interactive_type  1..6 (only when type = 2)
url               redirect target (only when type = 1)
ordering          step order within the tour
params            JSON, e.g. {"required":1,"requiredvalue":"Hello"}
language          language tag or *

8.2 The System Plugin and Shepherd.js

The visible part of a tour comes entirely from the System - Guided Tours plugin at plugins/system/guidedtours/. It does two jobs through subscribed events:

The drawing itself uses Shepherd.js, bundled under media/vendor/shepherdjs/ and wrapped by media/plg_system_guidedtours/js/guidedtours.js. Shepherd draws the popover, dims the rest of the page, and positions the highlight over the target element. When the plugin processes a tour, it maps the integer types to the strings Shepherd understands, for example step type 2 becomes interactive and interactive type 6 becomes select.

8.3 Recording State by AJAX

When the user completes, cancels, or skips an auto-starting tour, the browser calls the component's AjaxController::fetchUserState() task with three values: tid (tour id), sid (step number), and context (one of tour.complete, tour.cancel, tour.skip). The controller maps the context to a state (completed, delayed, or skipped) and saves it, but only for tours that actually auto-start.

Around that save, two events fire, which custom plugins can listen to:

onBeforeTourSaveUserState   fires before the state is written
onAfterTourSaveUserState    fires after, and can override the response message

This is the hook you would use to, for example, log tour completion to your own analytics, or to award a badge when a user finishes an onboarding tour.

8.4 Shipping Tours With Your Extension

Because a tour is just rows in two tables, an extension developer can ship ready-made tours inside an extension package. The user installs your component, module, or plugin, and the tours appear without any manual setup. There are two common ways to do this.

The first is an install SQL script. Joomla runs the SQL files referenced in your manifest at install time, so you add the inserts there:

INSERT INTO `#__guidedtours`
  (`title`, `uid`, `description`, `url`, `extensions`,
   `autostart`, `access`, `language`, `published`)
VALUES
  ('COM_MYEXT_TOUR_INTRO_TITLE', 'mycompany-myext-intro',
   'COM_MYEXT_TOUR_INTRO_DESC',
   'index.php?option=com_myext&view=items',
   '["com_myext"]', 1, 1, '*', 1);

INSERT INTO `#__guidedtour_steps`
  (`tour_id`, `title`, `description`, `target`, `position`,
   `type`, `ordering`, `language`, `published`)
VALUES
  (LAST_INSERT_ID(), 'COM_MYEXT_TOUR_INTRO_STEP1_TITLE',
   'COM_MYEXT_TOUR_INTRO_STEP1_DESC', '#toolbar-new', 'bottom',
   0, 1, '*', 1);

Note two things that keep the tour clean. The extensions value is a JSON array, so it must be valid JSON inside the SQL string. And the title and description hold language keys, not literal text, so you can ship the same tour translated into several languages (see section 7.3). Provide the matching strings in your extension's language files.

The second way is an installer script. If you need logic, for example to avoid duplicate inserts on reinstall or to update existing tours on upgrade, put the work in the install, update, and postflight methods of your script.php rather than in flat SQL. There you can boot com_guidedtours and use its model, which also runs the table's UID and validation logic for you:

$factory = Factory::getApplication()
    ->bootComponent('com_guidedtours')
    ->getMVCFactory();

$model = $factory->createModel('Tour', 'Administrator', ['ignore_request' => true]);
$model->save([ /* tour fields, as in section 9 */ ]);

Whichever route you choose, give every shipped tour a distinctive uid (for example mycompany-myext-intro) so it never collides with core tours or another extension's tours, and so your update script can find and refresh it later.

10. SEO and Discoverability

Guided Tours is a backend onboarding tool, not public content, so it has no direct SEO footprint. A tour never appears in your sitemap, never gets indexed by Google, and produces no public URL. Do not expect to rank for anything because you built tours.

It does, however, affect a different kind of discoverability, the one that matters inside your own admin:

• Good tours make features discoverable to your clients, which cuts support questions.
• The tour URL field is the closest thing to routing: it decides which screen a tour belongs to, so set it precisely.
• If you build a frontend tour (set the extensions broadly and target frontend elements), keep the popover text short; long popovers hurt the experience on mobile.

In short, think of Guided Tours as internal documentation that lives where the work happens, not as a marketing or search asset.

12. Best Practices

If you remember only a few things from this article, remember these:

• Keep tours short: five to eight steps beat a twenty-step marathon.
• Target by id or stable class, never by fragile deep selectors that break on upgrade.
• Always set the tour URL and Extensions so the tour only appears where it belongs.
• Use Autostart sparingly, and only for genuine first-run onboarding.
• Test autostart with a fresh user, because your own profile remembers completed tours.
• Re-check your tours after every Joomla update, since admin markup can shift.
• Use Access levels to give editors and administrators different tours on the same site.

14. Summary

Guided Tours turns Joomla into a self-teaching CMS. With nothing more than the backend, you can build interactive onboarding that highlights the right buttons, explains the right fields, and even waits for users to perform an action before moving on.

The essentials to take away:

• A tour is a container; its steps are popovers, and both are just database rows you edit in the admin.
• Steps come in three types (Next, Redirect, Interactive) with six interactive variants for hands-on tutorials.
• Targets are CSS selectors; stable ids make reliable tours.
• Autostart plus per-user state in #__user_profiles means a tour greets new users once without nagging them.
• The whole thing is drawn by the System - Guided Tours plugin using Shepherd.js, and there is no public REST API.

Built well, a handful of short tours can quietly remove the most common "how do I…" questions your clients ask. If you want to roll out guided onboarding across a Joomla site, or you have tours that broke after an upgrade and need a steady hand to fix the selectors, it pays to have someone who knows where every one of these pieces lives.