Guided Tutorial Extension Proposal #1

[gabrielc]

@KebabRonin

So the extra step with ‘Explore by myself’ would be more like an extra step which is part of the ‘Create a Page’ tour, and not some automatic popup which should show up for all tours/tasks implicitly?

I’m not sure if I 100% understand what you mean, so I’ll try to rephrase it in my own words. LMK if I got it right, please.

I think that by “extra step” you mean the modal notifying the user that they finished a task, and giving them the option to “explore by themselves” or to go to the “next task”.

This modal should appear by default at the end of each task, currently only during the “Getting Started” tour. The modal should take as input only the text to be displayed and a reference to the “next” task.
If the user clicks on “Explore by myself” at any time, the modal would not appear on subsequent task completions.

@KebabRonin

I’m asking whether to:

1. treat is as a regular step (so you have to create it yourself/copy it from an existing task if you want it at the end of your task)
2. treat it as a basic guided tour functionality (like you have a checkbox whether to include the extra ‘Explore by myself’ step in the tour, with some options for the skip/accept/description texts).

From end-user UX point of view both options above should lead to the same outcome, the question is about how to handle it on the task-creator-user UX/backend side.

In my opinion, (1.) treating it as a regular step would be more modular, as it wouldn’t introduce a new type of step to keep track of in the app. To make it more usable we could add step templates for the task-creator-user, but that seems a bit overkill for a feature most users don’t use.

While I also think option 1 would offer more modularity, I agree that it’s a bit overkill at the moment. If the modal is a regular step, I don’t see how it could be useful to have it in the middle of a task for example, since it would prompt the user to go to the next task. If we’re thinking about it as more of a way to display some information in the middle of a task, I feel like that would be a bit redundant since we can already do that with the pop-ups.

I’m more in favor of option 2. Having a checkbox somewhere on a config page (TBD), that enables a modal at the end of each task of a tour.

---

After the recent discussions, I’m currently in the process of updating the Design page to make it more explicit about what the extension should do, and how it should do it technically (for the things that we have agreed on in this forum post).

I’ll send a link when I’m done with the updates!

[gabrielc]

Another thing that came up in discussions is: should we still use xobjects to define tours, or should we use java components?

I’m not completely sure about the PROs and CONs of either. I’d appreciate some input from someone more technical here .

[surli]

@gabrielc

should we still use xobjects to define tours, or should we use java components?

I would establish the following pros and cons:

XObjects:

• Pros: easy to create and update from anyone directly inside the wiki, fits well with that we want to do here
• Cons: can be possibly edited by anyone in the wiki, so could be a security risk sometimes. No possibility to abstract things to reuse stuff between similar objects and might limit the possibility of customization

Java components:

• Pros: easy to reuse things and to test them
• Cons: needs to be a dev to define them, doesn’t really fit with the idea of allowing an extension contributor to create a tour quickly IMO

so for me we should still rely on xobjects for the Tour definitions, but we’ll probably need different xclasses, e.g. to define a tour, a step in a tour etc.

[Simpel]

We did a lot of adaptions to the tour. So it would be very nice to change with at least admin rights or below.

[gabrielc]

@surli

so for me we should still rely on xobjects for the Tour definitions, but we’ll probably need different xclasses, e.g. to define a tour, a step in a tour etc.

Given the pros and cons outlined above, I tend to agree that we should probably stick with XObjects. So +1 for XObjects on my side.

@Simpel

We did a lot of adaptions to the tour. So it would be very nice to change with at least admin rights or below.

Uuu!! That’s interesting! I was actually not sure if many people used the Tour App for custom tours. Would it be possible to share some details about how you use the current Tour App? It may prove helpful to know what works and what doesn’t in a real world scenario.

[Simpel]

Is there a way of exporting our tour in a way you can use it? Will a xar export do the trick?

[gabrielc]

Just tested it, and a XAR export should work fine.

[Simpel]

I zipped our 2 german tours and uploaded it to swisstransfer: SwissTransfer - Send large files securely and free of charge . It’s valid until 16.4.2026 at 15:26.

The adapted home page tour keeps it short and fast. The tour “Artikel erstellen” tries to show how to write an article. This tour broke at some major update on a point in the middle of the tour. I didn’t found time to fix this.

Some side notes:

• we removed the drawer on the right side (due to a11y reasons) and opened up the search input:

  

• we have a topmenu like this:

  

• we have on the left side the navigation panel only

[gabrielc]

I’ve looked over both tours and they’ve been really useful. Thank you!!
For the “Artikel erstellen” tour, I played around with it a bit. I didn’t manage to fix it but as some notes:

• the CKEditor toolbar is now hidden by default until the user clicks into the WYSIWYG editor (display: none;). This may break some steps
• The CSS selector for some editor elements has changed

The default behavior for errors in the current Tour App is to skip the problematic step. So you end up with the latter half of the tour steps being skipped .

Anyway! Thank you again for sharing your custom tours! It’s really helpful to see how the Tour App is used in the wild.

[tkrieck]

@gabrielc

Define backdrop click behavior

In Thiago’s mockups, the backdrop is transparent, only the popup is visible. This means that users may click on elements other than the highlighted element. How should we handle this?

I don’t have strong feelings towards the open backdrop. My original proposal for the mock up was to clearly signal the user that they can move anywhere else and effectivelly cancel the current step. But there are other ways to achieve this, like showing the backdrop and provide a “Quit Tutorial” button. The main point is that what we shouldn’t trap the user inside the tutorial, regardless of the method.

@gabrielc

What does it mean for the Guided Tour to be bundled in XWiki Standard?

We already agreed that the Guided Tour App should be bundled in XWiki Standard.
We have also agreed that we won’t deprecate the current Tour App until the Guided Tour App is of sufficient quality.
In this context, what does it mean for the Guided Tour App to be bundled in XWiki Standard?
Will it be installed but disabled by default? Will it not be installed but available for install by admins? Some clarifications would be necessary here.

By having feature parity we could start bundling it when the current tour could be remade in the new one, even if it doesn’t use the interactiveness of the guided tour.

@gabrielc

What happens when a child task is done during a parent task (e.g.: during the “Create a page” task, a user inserts an image on the page)?
Proposal: We only validate the currently running task. For example, if the user inserts an image on the page during the “Create a page task”, at the end of the task we only validate the “Create a page task”. The user could then start the “Insert an image on a page” task, and insert another image, or they could decide to skip the task entirely. We leave it up to the user.

Agreed

@gabrielc

If a user doesn’t want to follow our task order, of if they, for whatever reason, have to stop doing the initial tasks, then they are able to start tasks in whichever order they want, as long as those tasks don’t depend on other tasks,

Doesn’t this conflicts with: ?

@gabrielc

If the user skips the “Create page” task, we automatically create a page for them based on their username (e.g.: “Tutorial page for [USERNAME]”)

Perhaps we will have both types of tasks, skippable and unskippable.

Thanks for all the work on this and let me know if you need anything else to be mocked up.

[mleduc]

Hello all,

I’d like to come back to proposal 1 from the initial message:

@gabrielc

Proposal 1: The Guided Tutorial extension should be developed and bundled by default into XWiki Standard. The development process would follow all rules and quality requirements expected of a bundled component.

Instead of directly bundling the guided tour (actual name deciced in a separate discussion) in xwiki-platform.
I propose to first release it as a contrib extension.

This has the following benefits:

• The extension will be testable with more XWiki version (we are aiming for a parent of 18.4.0)
• We can iterate more incremental by not being tied to the release cycles of XWiki Standard

The goal is still to move the extension to xwiki-platform once it covers at least the same level of features as the current tour application.

Let me know what you think, I plan to create another discussion to request for the contrib extension git repository and jira project soon.
Thanks

[gabrielc]

@mleduc

I propose to first release it as a contrib extension.

@mleduc

The goal is still to move the extension to xwiki-platform once it covers at least the same level of features as the current tour application.

+1. Releasing now as a contrib extension would allow for more flexibility until the extension is ready to be merged in xwiki-platform.