Creating and managing tours

A tour is a sequence of steps that guides users through a CMS page or content edit page. Each item on the tour displays a tooltip on a targeted UI element—a field, cluster, tab, or widget—with a title and description.

Enabling tours

To create and manage tours, you must first enable the plugin.

1. Click > Admin > Plugins.
2. Click Tours.
3. Toggle on Enabled.
4. Click Save.

Permissions

The Tours plugin uses role-based permissions to control which users can see which tours, and what actions they can perform. Both permission types are configured on roles.

To configure tour permissions:

1. Click > Admin > Users & Roles.

2. In the Roles widget, select the role you want to configure, or click New Tool Role to create a new one.

3. Under Areas, ensure that the role has access to Admin -> Tours. This permission displays the Tours area under Admin in the left navigation.

   note

   Below are additional tours permissions. These permissions apply to existing tours. If this is your first time assigning permissions, and you have not yet made any tours, your options are limited. Brightspot gives you the option to create tours from this page, but recommends that you instead create tours from the specific contexts in which you want them (either from a CMS page or from an asset's content edit page). After creating tours on the desired pages or content edit pages, Brightspot then suggests coming back and making adjustments to the role and how it can interact with the now-existing tours.

4. Under Additional Permissions, click Add, then select Tours. These permissions determine which tours a user sees, and what actions they can perform.

   1. Under Tours, select the tour whose permissions you want to granularly manage (if none exist yet, you can create one).
   2. Under Actions, select the specific permissions that those users with this role will have regarding this tour (for example, you can prevent all users of a role from deleting the specified tour).

5. Click Save.

Tour types

The Tours plugin supports two types of tours:

Type	Description
Type tour	Attached to a content type. The tour appears on any asset's content edit page for that type.
Page tour	Attached to a specific CMS page path. The tour appears only on that page (for example, the dashboard).

Type tours

Type tours appear on every content edit page for a selected content type.

To create a type tour:

1. In the header, click .
2. From the Create list, select the content type for which you want to create a tour.
3. In the header, click .
4. Click .
5. In the Name field, type a name for the tour.
6. (Optional) Configure an initial tour popup. See Initial tour popup.
7. In the Items on the Tour field, add one or more steps. See Items on the tour.
8. Click Save.

Page tours

Page tours appear on a specific CMS page, such as the dashboard or a tool page.

To create a page tour:

1. Navigate to the CMS page for which you want to create a tour.
2. In the header, click .
3. Click .
4. In the Name field, type a name for the tour.
5. (Optional) Configure an initial tour popup. See Initial tour popup.
6. In the Items on the Tour field, add one or more steps. See Items on the tour.
7. Click Save.

Initial tour popup

Each tour can display an introductory popup before the first step. The popup presents a title and description to introduce the tour.

To configure the initial popup:

1. From the New Tour popup, click Initial Tour Popup, then click Set:.
2. In the Title field, type the popup title.
3. In the Description field, type the popup description.
4. Click Save.

Items on the tour

Each step targets a specific UI element and displays a tooltip with a title, description, and optional placement. Steps play in the order listed.

To add a step:

1. In the Items on the Tour field, click .
2. From the dropdown list, select the step type.
3. Complete the fields for the selected step type. See the sections below for each type.
4. Click Save.

tip

Reorder steps by dragging items within the Items on the Tour list.

Advanced (Developer)

An advanced step targets any UI element using a custom CSS selector. Use this type when no other step type matches your target element.

Field	Description
Positioning of tooltip in reference of featured item	Determines where the tooltip is located in relation to the featured item on the tour.
Title	Title of the item on the tour.
Description	Description of the item on the tour.
Selector Query	Tells the tour exactly which item on the screen to put the tooltip on when none of the built-in step types match what you intend to target. See the example below:

Selector Query example:

1
Quick Start Widget: 
2
.DashboardWidget:has(h2:contains("Quick Start")) a[href*="customize"]
3

4
Expand/Collapse Widget: 
5

6
button[aria-label="Expand/Collapse Widget"]

warning

Selectors that depend on generated class names or render order may break when the CMS is updated. Use stable DOM attributes such as data-* attributes where possible.

Cluster

A cluster step targets a group of related fields on a content edit page.

Field	Description
Select a Cluster	Select the cluster to feature on the tour.
Title	Title of the item on the tour.
Description	Description of the item on the tour.
Positioning of tooltip in reference of featured item	Determines where the tooltip is located in relation to the featured item on the tour.

Content widget

A content widget step targets a widget that appears in the content edit page.

Field	Description
Select a Widget	Select the content widget (i.e., URLs, Sites, etc.) to feature on the tour.
Title	Title of the item on the tour.
Description	Description of the item on the tour.
Positioning of tooltip in reference of featured item	Determines where the tooltip is located in relation to the featured item on the tour.

Dashboard widget

A dashboard widget step targets a widget on the CMS dashboard.

note

Dashboard widget steps are only available in page tours configured for the dashboard page.

Field	Description
Select a Widget	Select the dashboard widget (i.e., My Activity, Quick Start, etc.) to feature on the tour.
Title	Title of the item on the tour.
Description	Description of the item on the tour.
Positioning of tooltip in reference of featured item	Determines where the tooltip is located in relation to the featured item on the tour.

Field

A field step targets a specific field on a content edit page.

Field	Description
Select a Field	Select the field to feature on the tour.
Title	Title of the item on the tour.
Description	Description of the item on the tour.
Positioning of tooltip in reference of featured item	Determines where the tooltip is located in relation to the featured item on the tour.

Tab

A tab step targets a tab on a content edit page.

Field	Description
Select a Tab	Select the tab to feature on the tour.
Title	Title of the item on the tour.
Description	Description of the item on the tour.
Positioning of tooltip in reference of featured item	Determines where the tooltip is located in relation to the featured item on the tour.

Editing existing tours

To edit a tour from the admin area:

1. Click > Admin > Tours.
2. From the Tours list on the left, select the tour you want to edit.
3. Make any desired changes.
4. Click Save.

To edit a tour from the page it is configured for:

1. Navigate to the CMS page or open the asset's content edit page where the tour is configured.
2. In the header, click .
3. From the dropdown list, select the tour you want to edit.
4. Click .
5. Make any desired changes.
6. Click Save.

Previewing tours

Previewing a tour runs it immediately so you can see how it appears to users.

To preview a tour:

1. Navigate to the CMS page or open the asset's content edit page where the tour is configured.

2. In the header, click .

3. From the dropdown list, select the tour you want to preview.

4. Click .

   The tour starts immediately and steps through each tooltip in sequence.

Tour admin area

You can further manage tours from a dedicated admin area.

To access the Tours admin area:

1. Click > Admin > Tours.
2. From the Tours list, select a tour.
3. Update, archive, or delete a tour. For details, see Archiving tours and Deleting tours.

From this page, you can see all existing tours as well as archive or delete them.

Archiving tours

To archive a tour:

1. Click > Admin > Tours.
2. From the Tours list on the left, select the tour you want to archive.
3. Click Archive.
4. In the confirmation prompt, click OK.

Deleting tours

To delete a tour:

1. Click > Admin > Tours.
2. Open the archived tour's edit page.
3. Click Delete Permanently.
4. In the confirmation prompt, click OK.

warning

Deleting a tour removes it from all users' tour lists immediately. This action cannot be undone from the CMS UI.