Guided Tour Extension

Last modified by gabrielc on 2026/06/05 14:38

Description

Introduction


What is the Guided Tour Extension?

The goal of the Guided Tutorial Extension is to offer practical steps to newcomers. These steps should help new users better understand how to use XWiki properly. It will serve as a tutorial showcasing basic features of XWiki, such as: creating pages, commenting, annotating, uploading attachments & inserting images on pages, inserting macros, mentioning users etc.

A list of tasks would be available for users to go through. The available tasks would be influenced by the extensions installed on the wiki, and the rights of the user.

Why is it necessary?

The first time experience for end users, is currently quite brief. It doesn't offer enough details for people to understand how to properly use XWiki, leading to failure in adoption.

Definitions & concepts

Tour: A grouping of tasks.

Task: A grouping of steps.

Step: Individual actions a user has to take to accomplish something in the UI.

Technical requirements

The Guided tutorial extension has 2 main parts: the step by step tour functionality, just like the current Tour App, and the task widget that would display available tours and tasks.

Tour functionality

The main tour will be called "Getting Started". It will contain the tasks defined in the Task Selection section of this Design page.

Extensions will be able to provide their own tours and tasks. The tour name will, by default, be the same as the extension name. Task names are configurable by the tour creator.

Task dependency

Within a tour, tasks can depend on the completion of other tasks. A child task can only have a single parent task. Child tasks cannot depend on parent tasks from other tours, only tasks within the same tour.

A parent task can have multiple child tasks.

When a parent task is skipped, all child tasks should be skipped as well. 

If a child task is done during a parent task (e.g.: user inserts image on a page during the "create a page" task), we only validate the currently running task.

Child tasks should be visible in the widget, but appear disabled until the user finishes the parent task. On hover, a tooltip would appear (see HTMLElement: title property) with the text "To start this task, you must first complete [PARENT_TASK_NAM]". On mobile, the same text would permanently appear as a subtitle.

Modals

Modals are task steps without a target element set (works by default in driver.js).

For the "Getting Started" tour, modals will appear:

  • On first visit of the wiki
  • After a task is completed
  • After a tour is completed

Every modal will be added as a step.

This means that the first task of the "Getting Started" tour will start with a "welcome" modal. The "Getting Started" tour will start automatically on user first visit of the wiki. If the user dismisses the tour, it won't appear again (similar behavior to current Tour App).

Task skipping

Users will be able to skip any and all tasks. 

Tasks can be skipped by either starting a task, then clicking on the "Skip this task" link (see mockups bellow), or by hovering over a certain task in the Task widget, then clicking the skip icon that appears on hover.

If the user hovers over a whole tour, they can skip the whole tour the same way they skip tasks. If the user skips a whole tour, they will not see a modal congratulating them for finishing the tour, if they only skip tasks, they will see the modal.

Tour & task progress can be reset by hovering over a completed tour or task, then clicking on the reset icon that will appear on hover.

On mobile, actions that normally appear on hover on desktop, will always be displayed.

Other

Behavior for missing target element

In the occasion that a target element does not appear on the page for whatever reason, we should notify the user that something went wrong, then discard the progress made on the current task. The user should be able to manually restart the task after.

In the current Tour App, the behavior is to skip the step if the target element does not appear. This can work in the case of the Tour App since the extension usually just presents information. In the case of the Guided Tour, steps usually require action, meaning that a missing target element could compromise the whole task. This is why we decided to discard the task progress instead of skipping the problematic step.

Backdrop click behavior

If the user clicks outside the currently highlighted element, we use the "confirm on exit" feature of driver.js. This way we prevent misclicks from discarding the current task progress.

In future versions of the extension, backdrop interactions will be customizable by admins (color, transparency, click behavior etc).

API needs

The Guided Tour will need API endpoints for the following operations:

  • Create
    • Tour
    • Task
    • Step
    • User preferences
      • Widget position
      • Collapsed status
      • Closed status (if the user presses "x" on a collapsed widget)
  • Read
    • List of available tours
    • List of tasks available within a specified tour
      • Must be returned in order of expected completion
    • List of steps available in a specified task
      • Must be returned in order of expected completion
    • Tour completion status (is done = true / false)
    • Task completion status (is done = true / false)
    • User preferences
      • Widget position
      • Collapsed status
      • Closed status (if the user presses "x" on a collapsed widget)
  • Update
    • Tour
      • Metadata should include completion status, so tours can be updated as completed or not (e.g.: tour finish, skip, or reset) 
    • Task
      • Metadata should include completion status, so tasks can be updated as completed or not (e.g.: task finish, skip, or reset)
    • Step
    • User preferences
      • Widget position
      • Collapsed status
      • Closed status (if the user presses "x" on a collapsed widget)
  • Delete
    • Tour
    • Task
    • Step

Handling task order changes

If the order of a task is moved down from an upper position, the order of all the tasks between the new position and the previous position shift downwards by 1.

If the order of a task is moved up from a lower position, the order of all the tasks between the new position and the previous position shift upwards by 1.

Example: 

Moving a task down
Initial order:
1: Task A
2: Task B  <-- (This task moves down to 4)
3: Task C
4: Task D
5: Task E
6: Task F

After move order:
1: Task A
2: Task C  <-- (Task C shifts up from 3 to 2)
3: Task D  <-- (Task D shifts up from 4 to 3)
4: Task B  <-- (Task B moves here from 2 to 4)
5: Task E
6: Task F

Moving a task up
Initial order:
1: Task A
2: Task B
3: Task C
4: Task D
5: Task E
6: Task F  <-- (This task moves up to 2)

After move order:
1: Task A
2: Task F  <-- (Task F moves here from 6 to 2)
3: Task B  <-- (Task B shifts down from 2 to 3)
4: Task C  <-- (Task C shifts down from 3 to 4)
5: Task D  <-- (Task D shifts down from 4 to 5)
6: Task E  <-- (Task E shifts down from 5 to 6)

Task widget functionality

A widget containing all the available tours (by default only the "Getting Started" tour), and tasks should be visible in the bottom right section of the screen.

The widget will have the following elements:

  • Title bar
    • Minimize button
  • Main body
    • Tours
      • Tasks
  • Useful links

The widget should be collapsible, and draggable so that it doesn't block important content on the page.

When the widget is minimized, it's position on the screen is reset. This means that if the user dragged the widget from the bottom right to the bottom left, then minimized the widget, when they open up the widget again the widget will be back in the default position - bottom right.

A collapsed widget can also be closed entirely by clicking on the "x" icon to the right of the minimized widget handle. When the user clicks on the "x", a modal appears letting the user know that this action will completely remove the widget from every page until they manually reset this behavior. A link to the page where users can make the widget visible again should also appear in the modal.

Mobile responsiveness

The task widget will be responsive.

On mobile, the widget should be minimized by default, and present in the bottom right corner of the screen.

Upon clicking on the button in the bottom right corner of the screen, the widget would open, covering the whole screen.

When the user selects the task they want to do, the widget automatically minimizes itself and the user is guided to complete the task.

Space for tasks

The "Getting Started" tour requires users to create pages, leave comments, and generally do actions on the wiki. To not pollute the wiki, these actions will be done in the Sandbox space. 

In future versions of the extension, the extension will ship its own space and will allow configuring the space location.

The default space should already have permissions set up so that users can do the "Getting Started" tasks.

When users start a "Getting Started" task, they will be automatically redirected to their specific page within this space, to perform the action.

Future versions of the extension will offer admins utility to maintain this space. Utility tools will include: 

  • Ability to see a list of tour pages and when they were created
  • Ability to batch delete old tour pages
  • Ability to disable edit page notifications (should it be the default for pages in this space?)

Backwards compatibility

The Guided Tour extension is a revolution of the Tour App. While we will strive to offer feature parity, we shouldn't worry about doing it in a backwards compatible way, as the goal of the Guided Tour is not to be a drop-in replacement to the Tour App.

When the Guided Tour replaces the Tour App inside XWiki Standard, we should offer migration scripts between the 2 extensions for users that may need them.

Hierarchy

xwiki-platform-core/
└── xwiki-platform-guidedtour/
    ├── xwiki-platform-guidedtour-rest/          (dedicated REST endpoint)
    ├── xwiki-platform-guidedtour-webjar/        (packaging of the node packages)
    ├── xwiki-platform-guidedtour-ui/            (if necessary)
    ├── xwiki-platform-guidedtour-default-tour/  (default tours, should be easily excluded)
    ├── xwiki-platform-guidedtour-api/           (server-side API)
    └── xwiki-platform-guidedtour-default/       (default server-side implementation)

xwiki-platform-node/
└── src/
    └── main/
        └── node/
            └── core/
                └── guidedtour/
                    ├── guidedtour-api/           (Client-Side API)
                    ├── guidedtour-ui/            (Client-Side API)
                    └── guidedtour-xwiki/         (Client-Side implementation)

Mockups & Screens

Here are some mockups made by Thiago showcasing the basic flow.

Note: These are NOT final mockups. They will be updated based on received feedback.

For the tour popup, we could use what is listed here as a start: https://design.xwiki.org/xwiki/bin/view/Proposal/ImprovementsfortheOnboardingUI

An older proposal for tasks to Edit, Create Page, Customize Look & Feel: https://design.xwiki.org/xwiki/bin/view/Proposal/MultiPageTours

Task Selection

Implementation notes

  • Tasks are self-contained. No preconditions are necessary for any task. If a precondition seems necessary, it's better to update the task than to introduce the extra complexity into the codebase.
    • When a user starts a "Getting Started" task, they are always redirected to their tour page first. This way we ensure that every task starts at the same point.
    • Since we don't check for preconditions, if a user already is on their tour page, we will still redirect them to it when they start a task. This ensures a clean slate in case, for some reason, elements aren't fully loaded on the page, or the URL parameters are messing with the page.
  • Popover text for steps, modal text, and any other kinds of necessary text will be provided at a later time. During development dummy text should be used. Please indicate dummy text by prefixing it with "DUMMY-TEXT-" so that we know what kind of text is necessary, what needs to be updated and what was already updated.

0. Create an account

Task will be unchecked for guests and checked for logged-in users. Task will count towards tour progress. It's supposed to help logged in users perceive the tour as something that is already started.

1. Create a page

1.1. Click “Create” button
1.2. Prefill the title with "[USERNAME] Tutorial Page", show popover explaining to the user what the "Title" field is for, user has to click "next" in the popover to move to the next step
1.3. Select the "Guided Tour" template [we bundle the template with the extension, template will be created at a later time, use dummy template during development]
1.4. Click “Create”
1.5. Click “Done”

2. Leave a comment

2.1. Focus the “Comments (0)” section

2.2. Click the “Comments (0)” section

2.3. Click the “Comment” button

2.4. Add your comment [could be whatever, we shouldn’t check contents] -- Need input on how to handle this

2.5. Click “Add comment”

3. Add an annotation

3.1. Select some text and press “CTRL + M” [ or Command + M on Mac?]

3.2. Add your annotation text [could be whatever, we shouldn’t check contents] -- Need input on how to handle this

3.3. Click on “Add annotation”

[bring focus to Comments section]

3.4. Click on the quoted text above your annotation

4. Upload an attachment

4.1. Focus the “Attachments (0)” section

4.2. Click the “Attachments (0)” section

4.3. Click on “Browse…” under the “Attach files to this page” section

4.4. Select a file from your system

5. Insert a macro on a page

5.1. Click “Edit”

5.2. Type “/info”

5.3. Select the “Info Box” macro

5.4. Modify Info Box content (optional)

5.5. Click “Done”

6. Mention a user

6.1. Click “Edit”

6.2. Type “@”

6.3. Select a user

6.4. Click “Done”

7. Insert an image

[The template used for tutorial pages should contain at least one image, in case the user uploads another kind of document]

7.1. Click “Edit”

7.2. Type “/image”

7.3. Select the “Image” macro from the “Content” section

7.4. Select or upload an image

7.5. Click “Done”

8. View differences between 2 versions of the page

8.1. Focus the “History” section

8.2. Click “Compare selected versions”

Proposals


Guided Tutorial Extension Proposal #1

Link: https://forum.xwiki.org/t/guided-tutorial-extension-proposal-1/18115

Library choice for the new Guided Tour Extension

Link: https://forum.xwiki.org/t/library-choice-for-the-new-guided-tour-extension/18191

Choosing a name for the Guided Tutorial Extension

Link: https://forum.xwiki.org/t/choosing-a-name-for-the-guided-tutorial-extension/18294

Admin Section


Centralization of features that should be available in the admin section:

  • First release
    • Configure "Useful Links" in the widget
  • At a later time
    • Configure Space location for Guided Tour pages
    • Ability to see list of tour pages and when they were created
    • Ability to batch delete old tour pages
    • Ability to change notification status for page changes (disabled by default)
    • Ability to configure backdrop (transparency, color, other options available in driver.js)

About the current Tour App


The Tour Application is the current way in which XWiki guides first-time users. Once the Guided Tutorial Extension is released, the deprecation of the Tour App has been proposed.

Since the Guided Tutorial Extension is supposed to be a replacement and an improvement of the Tour App, we must ensure a smooth transition from one to the other.

The following projects are using the Tour App for custom tours:

ProjectNotes
xwiki/xwiki-platformXWiki Standard. Guided tours will be revamped as part of the development of the Guided Tutorial Extension.
xwiki-contrib/application-forumTBD
xwikisas/application-forumTBD. Fork of the contrib Forum Application.
xwikisas/xcsThe XCS project didn't receive any updates for the past 6 years. It's safe to assume it was discontinued. 

You can find a full list of the tour related files here.

A list of existing improvements/bugs opened for the current version of the Tour app (maybe some could be incorporated in the new Guided Tutorial Extension).

Tour Library Research


XWiki Standard Dependency Requirements

Source of requirements: Development Practices Guide (turn into local link).

RequirementMinimumDriver.JSConformity
Project longevityOver 2 years.First release in 2018Yes
Frequency of releasesSeveral times per year with a minimum of once per year if there’s a track record of it happening for more than 3 years.

Multiple releases in 2018 - 2019

No releases 2020 - 2022

Multiple releases 2023

No releases 2024

Multiple releases 2025

Partial
Speed of supportA question should be answered within a month at mostOut of 91 currently open issues, 64 have at least one comment. Not all comments are from the main maintainer of the project. Some comments are left months after the issue has been created.No
Number of active contributors

For dependencies providing:

  • an important feature: 3+ active developers
  • a secondary feature: 1+ active developer
1 main maintainer, semi active (mostly maintenance)Partial
Quality of documentationExistence of documentationDetailed documentation with code examples exists: https://driverjs.com/docs/installation.Yes
License compatibilityCompatible with XWiki’s LGPL 2.1 license, and OSI-approvedMIT licenseYes
Security issuesNo known important security issues-Yes
VersioningReleases are versioned properlyDriver.JS seems to be using Semantic VersioningYes

Features to look for:

  • License compatible with XWiki (LGPL-2.1)
  • Open Source
  • Well maintained
  • Vue/WebComponent compatible
  • Lightweight to load in the browser
  • Have a way to define tours as a user (so we can create tours for multiple extensions)
  • Possible to Highlight elements, ?advance tour on custom trigger (element click, form submitted, ...)?
  • Ease of customizing the UI to fit the XWiki style
  • Avoid writing our own library

Statistics collected on ~23 Jan 2026.
Live comparison: npm-compare

Namedriver.js (Demo)        v-onboarding (Demo)tourguide-js (Demo)vuejs-tour (Demo)
Activity

First Commit: 3 Mar 2018
Last Commit: 19 Nov 2025
Last Release: 19 Nov 2025

Number of releases: 19

Last 6 months: 1 committer

Total committers: 48 (+1 bots)
GitHub Stars: 25k
Activity Chart:

1769180154398-478.png

First Commit: 8 Dec 2021
Last Commit: 23 Jan 2026
Last Release: 23 Jan 2026

Number of releases: 31

Last 6 months: 1 committer

Total committers: 8 (+2 bots)
GitHub Stars: 199
Activity Chart:
1769180115460-227.png

First Commit: 11 Nov 2022
Last Commit: 6 May 2025
Last Release: 6 May 2025

Number of releases: 12

Last 6 months: 0 committers

Total committers: 10 (+0 bots)
GitHub Stars: 724
Activity Chart:
1769190251367-678.png

 

First Commit: 7 Dec 2022
Last Commit: 30 Jan 2026
Last Release: 30 Jan 2026

Number of releases: 43

Last 6 months: 2 committers

Total committers: 6 (+1 bot)
GitHub Stars: 106
Activity Chart:
1770208959903-536.png

Size

83kB Unpacked Size (npm)

25.24kB - minified js & css only (21.3kB + 3.94kB)

85.6kB Unpacked Size (npm)

24.71kB - minified js & css only (22.3kB + 2.41kB)

139 kB Unpacked Size (npm)

48.76kB - minified js & css only (44.3kB + 4.46kB)

123kB Unpacked Size (npm)

?15.82kB - minified js & css only (?13.8kB + 2.02kB)

Vue compatibleTypeScript Library (framework agnostic)
Could use the Vue Composition API
Vue3 nativeTypeScript Library (framework agnostic)
Could use the Vue Composition API
Vue3 native (Composition API)
Custom popup DOM

accept Yes (callbacks)
Backdrop: accept Yes (+supports cutout for element)

accept Yes (Vue Slots)
Backdrop: accept Yes (+supports cutout for element)

accept Yes (property)
accept Backdrop: Yes (+supports cutout for element)

accept Yes (Vue Slots)
accept Backdrop: Yes

Custom Actionsaccept Yes (callbacks configurable per step)

onNextClick(), onPrevClick(), onCloseClick() can be disabled and call the API to go to next step in a custom function
accept Yes (callbacks)

Can remove buttons and call the API to go to next step in a custom function
accept Yes (callbacks)

onBeforeStepChange(), onAfterStepChange(), onFinish() can be disabled and call the API to go to next step in a custom function

accept Yes (callbacks)

onTourStep, onTourEnd Vue events

Keyboard Navigationaccept Yescancel No (can be implemented through callbacks)accept Yesaccept Yes (new feature, disabled by default)
Licenseaccept MITaccept MITaccept MITaccept MIT
Notes

+ Large community, involved with PRs and issues

Project seems to be picked up again after a long period of inactivity

Can be integrated with Vue 3 by using the composition API pattern. Some repos exist, but are not maintained: https://github.com/wobsoriano/vue-driver

Other integration examples: https://deepwiki.com/kamranahmedse/driver.js/4.3-integration-examples

- Many stale PRs
- Only 1 constant contributor. The project is developed only by 1 person, but the community seems to be actively involved in it

- Looks like an activity spike recently after a long break, might be misleading. activity frequency

- Only 1 constant contributor

- small community

+ Performance was pretty smooth in my experience

Uses Floating-ui for tour positioning. Floating-ui is a open source, MIT licensed project. It is well maintained by multiple contributors.

- Issue with Vue integration

- Only 1 constant contributor

- Small community

- Still in alpha version

+ Can save to local storage
+ Can switch between 2 tours on the same page
- Accessibility features are disabled by default (they are a recent addition)
Namedriver.js (Demo)        v-onboarding (Demo)tourguide-js (Demo)vuejs-tour (Demo)
API example
const driverObj = driver({
  showProgress: true,
  steps: [
    { element: '.page-header', popover: { title: 'Title', description: 'Description' } },
    { element: '.top-nav', popover: { title: 'Title', description: 'Description' } },
    { element: '.sidebar', popover: { title: 'Title', description: 'Description' } },
    { element: '.footer', popover: { title: 'Title', description: 'Description' } },
  ]
});
<script setup lang="ts">
import { ref } from 'vue'
import { VOnboardingWrapper, VOnboardingStep } from 'v-onboarding'
import 'v-onboarding/dist/style.css'

const wrapper = ref(null)
const steps = [
  {
    attachTo: { element: '#feature-1' },
    content: { title: 'Welcome!', description: 'Let me show you around.' }
  },
  {
    attachTo: { element: '#feature-2' },
    content: { title: 'Next Feature', description: 'Here is another feature.' }
  }
]
</script>

<template>
  <VOnboardingWrapper ref="wrapper" :steps="steps" />

  <button @click="wrapper?.start()">Start Tour</button>

  <div id="feature-1">Feature 1</div>
  <div id="feature-2">Feature 2</div>
</template>
const tg = new TourGuideClient(options);

tg.addSteps([
  {title:'Step 1', content: 'content', target: '#input'}
]);
// Can also define steps inline with html elements:
<div data-tg-tour="Welcome to the tour"
data-tg-title="Get started"
data-tg-group="my-first-tour"
data-tg-scroll-margin="0"
data-tg-fixed
> ... </div>
<template>
  <div>
    <div id="selectByID">Selected by its id 'selectByID'</div>
    <p class="selectByClass">Telected by its class 'selectByClass'</p>
    <button data-step="3">Selected by the 'data-step="3"' attribute</button>

    <VTour :steps="steps"/>
  </div>
</template>

<script setup>
const steps = [
  {
    target: '#selectByID',
    content: 'This is the first step',
  },
  {
    target: '.selectByClass',
    content: 'This is the second step, placed on the bottom of the target',
    placement: 'bottom',
  },
  {
    target: '[data-step="3"]',
    content: 'This is the third step',
  }
];
</script>

Other libraries which were looked at:

  • guida.js (Demo) - MIT, not updated new project (20 Aug 2025 - 1 Sep 2025), 1 committer (+1 bot), (demo includes custom trigger for next step, can add custom CSS classes, but no keyboard navigation (even though they claim they have it))
  • vue-onboarding-tour (Demo) - MIT, (11 Nov 2024 - 8 Nov 2025), 2 committers (the library is one vue file, with some extra css)
  • Onborda (Demo) - no license, abandoned (5 Mar 2024 - 22 Dec 2024), 2 committers, nextjs only?, (feels floaty, no keyboard navigation)
  • Vue Page Guide (Demo) - MIT, abandoned (8 Oct 2018 - 19 Oct 2018), 1 committer, (looks like a personal project, no keyboard navigation, but interesting demo with multiple popups at the same time)
  • tourguide.js - BSD-3-Clause license, not updated (17 Apr 2019 - 24 Mar 2025), 4 committers (+1 bot)
  • Vue Tour - MIT, abandoned (15 Feb 2018 - 22 Apr 2021), 16 committers (+1 bot),
  • Lusift - MIT, abandoned (13 Mar 2022 - 16 Aug 2022), 1 committer, (looks like a personal project)
  • User Tour- incompatible AGPL-3.0 license, fairly new project (24 Jan 2025 - 9 Jan 2026), 5 committers, (no demo, cloud-based solution, but has included a checklist implementation)
Shepherd (Demo)ErrorAGPL-3.0

Free for OSS?

INCOMPATIBLE LICENSE

First Commit: 17 Dec 2013
Last Commit: 20 Jan 2026
Last Release: 24 Jul 2025 (Last non-commercial-license release: 8 Oct 2024) 
Activity Chart:1769182395244-743.png

Last 6 months: 2 committers

Total: 105 (+4 bots)

+ Keyboard navigation (arrow keys, esc)
+ Can add custom CSS classes
+ Has callbacks?

+ 13k stars on github
+ Typescript
+ Has an official vue wrapper

+ From their website: "Shepherd.js is free for open-source, personal and non-commercial sites. If your project is non-commercial, you can use Shepherd.js for free.", but the license might still be an issue

 

Intro.js (Demo)

ErrorAGPL-3.0
Free for OSS?
 

INCOMPATIBLE LICENSE

First Commit: 10 Mar 2013
Last Commit: 4 Jan 2026
Last Release: 13 Jul 2025 (Last non-commercial-license release: 21 Dec 2015) 
Activity Chart:1769181551341-225.png

Last 6 months: 2 committers

Total: 104 (+2 bots)

+ Keyboard navigation (arrow keys, esc)
+ Can add custom CSS classes
+ Has Tour and Hint implementation
+ Configurable progress UI: progress bar, progress bullets, next/prev buttons, alert confirmation on skip
+ Has callbacks for before/after each step, on tour start/exit
+ Animated transitions~

+ 23k stars on github
+ Typescript

+ From their website: "Intro.js is free for open-source, personal and non-commercial sites. If your project is non-commercial, you can use Intro.js for free.", but the license might still be an issue

Alpha version

Draft PR link

Installation instructions

If you want to test a buggy, WIP prototype, on your local test instance, do the following:

  1. Download the xip file on this page
  2. Use the code from https://snippets.xwiki.org/xwiki/bin/view/Extension/XIPImporter/ to import the xip
  3. Install the guided tour extension from the Extension Manager http://localhost:8080/xwiki/bin/admin/XWiki/XWikiPreferences?section=XWiki.Extensions&extensionId=com.xwiki.tour%3Aapplication-guided-tour-ui&extensionVersion=0.0.1-SNAPSHOT
  4. Keep the new version of the page when asked to merge

Note: This will overwrite your Tour application.

Getting unstuck

You can try to clear the localStorage

What is implemented

  • Uses the Tour Application code
    • Updated Pages: StepClass (tentative changes, not actually used), TourJS
    • New Pages: TourRESTSource
    • New Tours:
      • Create-a-page: Auto-Start on Sandbox, must create page named 'newpage' for this alpha/demo version
      • Leave-a-comment: Auto-Start on Sandbox
    • All existing tours should be compatible with this new app (like the default Homepage tour, forum tour - untested)
    • Driver.js CSS pasted into TourJS SSX
  • TourRESTSource
    • List all tasks on the wiki, with all their steps & parent tours
  • Persistence (localStorage keys)
    • tour_{tourName}_current_step - same as current Tour Application
    • tour_{tourName}_end - same as current Tour Application
    • tour_{tourName}_TourFloaterTourCollapsed - whether the tour is collapsed in the floater
    • TourFloaterCollapsed - whether the floater is collapsed
    • Also a lookup table from url path -> task would be nice, to reduce the load on the client having to see what task to auto-activate on a page
      • Disable autostart? No, it's supported by the old Tour Extension
  • Guided Tour floater
    • Tasks are fetched from TourRESTSource (localStorage cache could be implemented)
    • Can be collapsed/dragged left-right with the mouse if the floater covers something on the page
    • Tasks grouped by space
    • You can start tasks by clicking on their titles
    • Progress is tracked & computed as % of total tasks
    • Some preference persistence (floater is open/collapsed, which tours are open/collapsed)
  • Tasks
    • Compatible/the same format as the Tour Application
    • Auto-start code inherited from Tour Application
    • Persistence (step number for multi-page tasks, tour end)
  • Steps
    • Going Next on a step which requires user action AND would redirect to a new page is forbidden
    • If an element doesn't exist, it is waited 2.5s, after which if it is not found, nothing happens
    • Supported reflex/user actions: click element, wait 5s after clicking a text input
  • If you want to create a tour, here are the options:
    • Reflex: whether to advance on user clicking the highlighted element (also hides next/prev buttons)
    • <DOESN'T FULLY WORK> Backdrop: whether to show the background
    • Target page, Target action: Should work (to match the page path like /xwiki/bin/ACTION/PAGE) - Target query string doesn't work
      • Target page & action are inherited from the previous steps, so you don't have to define them for each step. You can define them only when the page/action changes
    • DON'T WORK: Placement,tempJS_step, tempJS_extra, step_id, Target query string
    • The Tour property for Target Class might work, but I didn't test it

More features to implement

  • Congratulations message on tour (all tasks) completion
    • Should be able to customize from Admin section the checkbox of whether to delete the tour demo page
  • <To discuss how> Admins should have option to batch delete tour demo pages older than X days
  • More validation for moving on to the next step (that the element exists, the same page/path, that no error notifications appeared?)
  • Add resize dragger for floater height
  • Make use of localStorage key tour_{tourName}_redirect_to - as it was used in the original Tour App too
  • Skip steps if their associated element doesn't exist (from original Tour App)
  • Disable backdrop per step
  • Use all the attributes given by the original Tour App
  • <To discuss how> Preconditions aka Conditional Task/Step dependencies
  • Skip tasks directly from floater
  • Hide(or disable?) tasks until some other task is completed (eg. Create-a-page must be done before Add-a-comment is available)
  • The extension should ship with its own space + template.
    • The space would be excluded from search, as to not pollute searches.
  • Do some javascript before starting a task (eg. Redirect to some space)
    • If a task depends on some page, redirect there
    • If the page doesn't exist, redirect to some default page (like the USERNAME_tour page described below)
  • Do some javascript when a task is skipped (eg. If you skip Create-a-page, automatically create a USERNAME_tour page)
  • Mandatory tours/tasks
  • [Not 1.0] Hidden tasks for one-off hints (eg. "Press 'Ctrl+G' instead of '/' like on github")
  • [Not 1.0/Out of scope] UIX for floater for any app to use is out of scope

 


Get Connected