Explanation

How the Guided Tour extension is structured and how its components interact.

Overview

The extension follows a layered architecture with a Java backend and a TypeScript/Vue 3 frontend, connected through REST APIs and XWiki's document model.

Data model

Tours use XWiki's document and object model for storage:

Tour (XWiki document + TourClass XObject)
  +-- Task1 (child document + TaskClass XObject)
  |     +-- Step1 (StepClass XObject on task document)
  |     +-- Step2 (StepClass XObject on task document)
  +-- Task2 (child document + TaskClass XObject)
        +-- Step3 (StepClass XObject on task document)

Each tour is a single XWiki document. Tasks are child documents nested under the tour. Steps are XObjects stored on their parent task document.

User progress is stored in localStorage. This means that user progress will not sync across user devices.

Module layering

API layer (guidedtour-api)

Defines the public contract: DTOs (TourDTO, TaskDTO, StepDTO, UserTourStatusDTO), enums (Placement, ActionType, Status, WidgetState), and exceptions (InvalidIdException, DuplicatedIdException). This module has no implementation dependencies.

Service layer (guidedtour-default)

Implements the core business logic. Four manager classes handle CRUD operations:

• ToursManager - tour CRUD operations through DTOs
• TasksManager - task CRUD operations through DTOs, with ordering and dependency resolution
• StepsManager - step CRUD operations through DTOs, with ordering
• UserStatusManager - per-user progress persistence

Managers use XWiki's document API for storage and Solr queries for listing.

REST layer (guidedtour-rest)

Exposes the service layer as REST endpoints. Two sub-modules separate contract (guidedtour-rest-api) from implementation (guidedtour-rest-default). A base class (AbstractGuidedTourResource) handles CSRF validation, authorization checks, and error mapping.

For a more in-depth description of all available endpoints, see the REST API documentation page.

UI layer (guidedtour-ui)

An XAR package containing XWiki pages, classes, sheets, translations, and a UI Extension (Bound on org.xwiki.platform.template.header.after) that injects the widget into the page header. The GuidedTour.WebHome page provides a LiveData table for tour management.

Frontend layer

The widget is a Vue 3 application built with TypeScript and driver.js:

• @xwiki/contrib-guidedtour-api - TypeScript interfaces mirroring the Java DTOs
• @xwiki/contrib-guidedtour-xwiki - XWiki-specific implementations: REST client (GuidedTourRestClient), tour player (DefaultGuidedTourManager), storage manager, and caching (TourStore)
• @xwiki/contrib-guidedtour-ui - Vue 3 components (GuidedTourWidget and sub-components)

The widget is packaged as a WebJar and injected into every page via a UI Extension hook.

Data flow

1. The Vue widget initializes on page load and fetches available tours from the REST API.
2. User progress is loaded from the localStorage
3. When a user starts a task, the frontend fetches the steps and initializes the driver.js overlay.
4. Navigation between steps updates the driver.js highlight position. All data related to a tour in progress (cached steps, current step index, task id) is saved in sessionStorage.
5. Task completion updates the localStorage user progress state.

Key design decisions

• XWiki document model - Tours leverage XWiki's native storage and permission system. No separate database is required.
• CSS selector-based targeting - Steps use CSS selectors to determine which elements to target, making tours customizable and adaptable to different skins.
• REST API abstraction - All CRUD operations are available through REST endpoints, enabling third-party integrations.
• Session storage for multi-page tours - Active task state is stored client-side to survive page navigation without server round trips.
• Legacy compatibility - The extension detects the legacy Tour Application and disables itself to prevent conflicts.

Dependencies

• driver.js - Lightweight overlay engine for step highlights and tooltips
• Vue 3 - Reactive UI framework for the widget
• Vite - Build tool for the frontend bundle
• XWiki REST API - Server-side extension points and document APIs
• Solr - Used for efficient listing queries