Technical reference

The Tours plugin provides a framework for creating and delivering interactive, step-by-step walkthroughs within the Brightspot CMS. It stores tour data as Brightspot Record objects, delivers step data as JSON via an internal endpoint, and renders tooltips in the browser using Shepherd.js.

Dependencies

The Tours plugin depends on the following Brightspot platform libraries:

• com.brightspot.db:db
• com.psddev:cms-db-internal
• com.psddev:dari-html
• com.psddev:dari-web
• com.fasterxml.jackson.core:jackson-annotations
• com.github.ben-manes.caffeine:caffeine

Installation

Requirements

Requires Brightspot 4.8 or later.

Maven

<dependency>
    <groupId>com.brightspot.tours</groupId>
    <artifactId>tours</artifactId>
    <version>__HIDDEN__</version>
</dependency>

Gradle

implementation 'com.brightspot.tours:tours:__HIDDEN__'

Gradle (Kotlin DSL)

implementation("com.brightspot.tours:tours:__HIDDEN__")

API reference

Core classes

Tour

Abstract base class for all tour records. Extends Record and implements Global, Serializable, and ContentEditable. Subclassed by TypeTour and PageTour.

Method	Return type	Description
getTourItems()	List<TourItem>	Returns all steps configured for the tour. Implemented by subclasses.
getFilteredTourItems()	List<TourItem>	Returns only steps where includeInTour() returns true.
getTourId()	String	Returns the tour's UUID as a string.
getTourInitialName()	String	Returns the initial popup title.
getTourInitialDescription()	String	Returns the initial popup description.
getExistingInstances(String subject)	List<Tour>	Queries for tours configured for the given subject (an ObjectType UUID or a page path).
getNewInstance(String subject)	Tour	Creates a new TypeTour or PageTour appropriate for the given subject.
shouldContentBeEditable()	boolean	Returns true if the current user has the CREATE action permission.

TypeTour

Extends Tour. Represents a tour attached to a specific content type. The tour appears on every content edit page for that type.

Field	Type	Description
contentType	ObjectType	The content type this tour is attached to. Set automatically on save; read-only in the UI.
tourItems	List<TourItem>	The steps in this tour. Does not include TourDashboardWidget steps.

PageTour

Extends Tour. Represents a tour attached to a specific CMS page path.

Field	Type	Description
page	String	The CMS page path (for example, /cms/index.jsp). Set automatically from the request; read-only in the UI.
tourItems	List<TourItem>	The steps in this tour. Includes TourDashboardWidget steps when the page is the dashboard.

Tour item classes

TourItem

Abstract base class for all tour step types. Extends Record and is annotated @Recordable.Embedded.

Method	Return type	Description
getSelectorQuery()	String	Returns the CSS selector used to locate the target UI element.
getTourType()	String	Returns a string identifier for the step type (for example, "field", "cluster").
getDefaultTourPlacement()	TourPlacement	Returns the default tooltip placement for this step type.
getTourPlacement()	String	Returns the lowercase placement value (for example, "right"), resolving to the default if none is configured.
getTourTitle()	String	Returns the tooltip title.
getTourDescription()	String	Returns the tooltip description.
getDescriptionFallback()	String	Override to provide a default description when none is configured. Returns null by default.
includeInTour()	boolean	Returns true if this step should be included when rendering the tour.

TourField

Targets a specific field on a content edit page. Selector format: [data-field="fieldName"]. Default placement: right. A TourField step is excluded from the tour (includeInTour() returns false) when both its title and description are blank and no matching TypeGuide field description is available. If TypeGuide supplies a description for the field, getDescriptionFallback() returns it and the step is included.

TourCluster

Targets a cluster (group of related fields) on a content edit page. Selector targets the cluster header element. Default placement: right.

TourTab

Targets a tab on a content edit page. Selector format: button[data-tab="tabName"]. Default placement: bottom.

TourDashboardWidget

Targets a widget on the CMS dashboard. Selector format: [data-widget-id="..."]. Default placement: right.

TourDataPage resolves the widget ID at request time by inspecting the rendered dashboard. If the widget uses a dynamic ID rather than the default UUID3 derived from the class name, the data endpoint sets overrideWidgetId on the step before serializing.

TourContentWidget

Targets a content edit widget. Selector format: [data-widget-id="..."] derived from widget state. Default placement: left. Only widgets not placed in a dedicated tab are available for selection.

AdvancedTourItem

Allows targeting any UI element using a custom CSS selector. Use when no other item type matches the target.

TourPlacement

Enum of tooltip placement options: TOP, BOTTOM, RIGHT, LEFT. Each value exposes getPlacementValue(), which returns the lowercase string used in the JSON payload.

History tracking

TourHistory

Tracks when each user last viewed each tour. Keyed by a compound userIdAndTourId field. The static methods getHistory, createHistory, and getOrCreateHistory are package-private and used internally by TourDataPage and TourSeenPage; they are not part of the public extension API.

TourDataPage maintains a Caffeine cache (USER_AND_TOUR_LAST_VISIT_DATE_CACHE) with a one-hour TTL and a maximum of 1,000 entries. The cache is used when determining whether to auto-show a tour on page load.

Permission classes

TourAction

Enum of the two available tour actions:

Value	Permission ID
CREATE	tour/action/create
DELETE	tour/action/delete

TourActionPermission

Abstract embedded record. Controls what actions a user can perform. Concrete subclasses: AllTourActionPermission, NoneTourActionPermission, OnlyTourActionPermission, AllExceptTourActionPermission.

ToursConfigured

Abstract embedded record. Controls which tours a user can see. Concrete subclasses: AllToursConfigured, NoToursConfigured, OnlyToursConfigured, AllToursConfiguredExcept.

TourToolRolePermissionSettings

Extends AdditionalPermission. Combines a ToursConfigured instance and a TourActionPermission instance to provide complete tour permission configuration on a Brightspot role.

Plugin configuration

TourPlugin (a Brightspot Plugin record) exposes a single global toggle:

Field	Type	Description
enableTours	Boolean	When true, enables the plugin globally. When false or unset, tours are disabled and the Tours button does not appear in the CMS header.

Configure this setting in Admin > Plugins > Tours.

Extending the plugin

Creating a custom tour item type

Extend TourItem and implement the three required methods to add a new step type.

1
public class CustomTourItem extends TourItem {
2

3
    private String targetId;
4

5
    public String getTargetId() {
6
        return targetId;
7
    }
8

9
    public void setTargetId(String targetId) {
10
        this.targetId = targetId;
11
    }
12

13
    @Override
14
    public String getSelectorQuery() {
15
        return "[data-my-element=\"" + getTargetId() + "\"]";
16
    }
17

18
    @Override
19
    public String getTourType() {
20
        return "custom";
21
    }
22

23
    @Override
24
    public TourPlacement getDefaultTourPlacement() {
25
        return TourPlacement.BOTTOM;
26
    }
27
}

note

The string returned by getSelectorQuery() is passed directly to the front-end Shepherd.js integration. Use stable DOM attributes such as data-* attributes. Selectors that depend on generated class names or render order may break across CMS updates.