[5.2] [Guided tours] Auto start tours - full functionality

[obuisard]

Summary of Changes

The welcome tour has been introduced in Joomla 5.1. It is a tour that starts automatically any time a new instance of Joomla has been installed. However, at that time, we could not introduce a full implementation. Therefore, the welcome tour was meant to run only once and pretty much only for the person who installed Joomla.

This PR is meant to add the missing functionality of the auto-starting tours.

It adds several enhancements:

• a way for the users to opt-out of this functionality, as auto-starting tours can be a 'nuisance' for some (although tours can quickly be discarded by selecting the new button 'Hide Forever'),
• a way to log user behavior in the User Action Logs (by opting-in the guided tours in the action logs, one can find out if a user skipped, completed or cancelled a tour and at what step) - which works for all tour, not just the auto-starting ones,
• a way to make any tour an auto-starting one (see complementary PR [5.2] [Guided tours] Add missing auto start parameter in the user interface of tours #43690),
• a way to store the tour state for every user in the User Profiles table (specific to auto-starting tours),
• the possibility to run a tour after a specific delay when a user has cancelled an auto-started tour,
• the possibility to keep running tours manually even if they have been skipped or previously completed.

Many thanks to Shirielle Williams @sdwjoomla, Marc Studer (co-implementer), Adam Melcher and the Guided Tours team for their work and feedback.

Testing Instructions

Download the full and update packages from the Downloads checks.
You cannot test this PR through the patch tester extension.

Test 1 - on a new instance

Install the full package of this PR.
The welcome tour will run and you should see a button 'Hide Forever'. Do not select the button.
Cancel the tour (with the X).

Go to Guided Tour's global configuration.
Set the time for the delay parameter to 1 minute (this will help testing the cancelling of tours when they auto-start).
Save.
When a tour auto-starts, cancelling it prevents the tour from running again for a certain period of time (hence the delay parameter).

Go to Users -> Users Action Logs
Filter by the 'Guided Tours' extension. The extension will NOT be in the list if there are no recorded logs yet.
You should see User [you] delayed the tour 'Welcome to Joomla!'.
On a new instance of Joomla, the Guided Tours action logs are enabled by default.
It has probably been a minute since you cancelled the tour, so go back to the dashboard.
The welcome tour should run again.
Cancel the tour (with the X).

Test 2 - opt-out of auto-starting tours
Goal: disable auto-starting tours for all users

Go to Guided Tour's global configuration.
Disallow the auto-starting of the tours.
Save.
Go back to the dashboard.
Make sure a minute has passed.
Refresh the page if necessary.
The welcome tour should no longer start.

Test 3 - opt-out of auto-starting tours for a single user
Goal: disable auto-starting tours for one user

Go to Guided Tour's global configuration.
Allow the auto-starting of the tours.
Save.
Go back to the dashboard.
The welcome tour should run again.
Cancel the tour (with the X).
Go to your user profile.
In the 'Basic settings' tab, select the option 'no' for the 'auto starting tours' parameter.
Save.
Go back to the dashboard.
Make sure a minute has passed.
Refresh the page if necessary.
The welcome tour should no longer start.

Test 4 - opt-out of the welcome tour
Goal: opt-out of a tour that starts automatically

Go to your user profile.
In the 'Basic settings' tab, select the option 'Use default' for the 'auto starting tours' parameter.
Save.
Go back to the dashboard.
The welcome tour should run again.
Select 'Hide Forever' button to dismiss the tour completely.
Go to Users -> Users Action Logs
Filter by the 'Guided Tours' extension.
You should see User [you] skipped the tour 'Welcome to Joomla!'.
Go back to the dashboard.
Make sure a minute has passed.
The tour should no longer start by itself.

Test 5 - run the welcome tour manually
Goal: possibility to run tours that have been skipped previously

Go to the guided tour list of tours at the top of the dashboard and run the welcome tour.
The 'Hide forever' button should be missing.
Running the tour manually should not interfere with your decision to skip the tour or if you have completed it. In those 2 cases, the tour should never auto-start again.

Test 6 - auto start 2 welcome tours
Goal: test the sequencing of tours when several tours are set to run on the same page

Go to System -> Guided Tours (in the 'Manage' section).
Select the welcome tour (it should be the last on the list of tours).
Save as copy. Publish the tour. Change the title to your liking (by replacing the language key). Save and close.
No need to add steps for this test.
Copy the tour a second time (change title, publish and save) to create a 3rd welcome tour (remember, the first welcome tour should never show again).
Now you have 2 auto-starting tours ready to go.
Go to the home dashboard.
The first auto-starting tour should start. Cancel by clicking on the X.
Nothing else should happen.
Go to Content -> Articles (or just refresh the page). Go back to the home dashboard.
The second tour should start unless the first tour's delay has already passed.
Cancel the tour with 'X'.
Wait one minute, refresh the page. The first tour should start again. Hide forever.
Wait one minute, refresh the page. The second tour should start. Hide forever.
No tour should show again after one minute, no matter what you do (refresh the page, do something - like checking the user action logs - and go back to the home dashboard).

Test 7 - on an updated instance
Goal: test settings on update

Install the update package of this PR over a 5.1 instance or earlier version of 5.2 (there was no welcome tour in 5.0).
The welcome tour should not run, it has been disabled from auto-starting after it has ran once in Joomla 5.1.
Go to the User Action Logs global configuration.
The Guided Tours should not be selected.

Note

PR #43690 has been merged and therefore you can now change auto-start settings for tours when editing a tour.

Actual result BEFORE applying this Pull Request

The welcome tour starts and only one user can see it. It runs only once. To see it again, the tour needs to be run manually.

Expected result AFTER applying this Pull Request

Any tour set to auto-start should automatically run, one at a time, when in the context it is supposed to run under.
Tours run automatically for all users logging in the backend (if the tour is available for the user group the user is part of).
When a tour is cancelled, it restarts after a certain delay. When skipped (hidden forever) or completed, the tour no longer runs.
All tours are still available to run manually.
Manual tours do not have the button 'Hide forever'.

Link to documentations

Please select:

• Documentation link for docs.joomla.org: Guided Tours Options

• No documentation changes for docs.joomla.org needed

• Pull Request link for manual.joomla.org: Auto-start and events

• No documentation changes for manual.joomla.org needed

Note:
User and User Action Logs help screens are severally out of date and it's impossible to add information related to this PR without adding the already missing information and re-creating screenshots.

[obuisard]

The code in the controller changing the dB should be in the model.

I moved the controller's database calls to the tour model.

[brianteeman]

You've made changes to the cypress tests here but you havent updated the joomla-cypress package

[obuisard]

You've made changes to the cypress tests here but you havent updated the joomla-cypress package

I have created joomla-projects/joomla-cypress#27

[brianteeman]

and then you need to update your branch to use that - ie npm update joomla-cyprus

[muhme]

Olivier: I have created joomla-projects/joomla-cypress#27
Brian: and then you need to update your branch to use that - ie npm update joomla-cyprus

And I have created joomla-projects/joomla-cypress#31. From my point of view we need to wait for merge and new NPM joomla-cypress release 1.1.1 to be created. After that devDependencies change "joomla-cypress": "^1.1.1" and npm update joomla-cypress and change back from skipTour to cancelTour is needed.

In the meantime and as joomla-projects/joomla-cypress#27 is already merged but not released, temporary solution is to change package.json:

     "joomla-cypress": "github:joomla-projects/joomla-cypress",

and run npm update joomla-cypress.

[webiedesign]

Test 1 - on a new instance - successful
Test 2 - opt-out of auto-starting tours -tested several times on/off all were successful
Test 3 - opt-out of auto-starting tours for a single user -tested several times on/off all were successful
Test 4 - opt-out of the welcome tour - successful
Test 5 - run the welcome tour manually - successful
Test 6 - auto start 2 welcome tours - successful
Test 7 - on an updated instance - I did a fresh install of 5.1.2, the welcome tour did run once.There was no indication of the user clicking out of it with the X . The tour did not run again. My copy of the welcome tour did not copy the steps as it did in the full install. After adding a step and toggling the auto-start to yes in the tour it performed as expected- successful

[obuisard]

Test 1 - on a new instance - successful Test 2 - opt-out of auto-starting tours -tested several times on/off all were successful Test 3 - opt-out of auto-starting tours for a single user -tested several times on/off all were successful Test 4 - opt-out of the welcome tour - successful Test 5 - run the welcome tour manually - successful Test 6 - auto start 2 welcome tours - successful Test 7 - on an updated instance - I did a fresh install of 5.1.2, the welcome tour did run once. There was no indication of the user clicking out of it with the X . The tour did not run again. My copy of the welcome tour did not copy the steps as it did in the full install. After adding a step and toggling the auto-start to yes in the tour it performed as expected- successful

Thank you Mary.
Copying a tour does not copy the steps, unless you duplicate the tour from the list of tours.
Can you set the test to successful in the issue tracker (at https://issues.joomla.org/tracker/joomla-cms/43814)? Thank you so much!

[terryburg]

I have tested this item ✅ successfully on dfd42fc

Marked successful because all the desired outcomes were achieved, I think.

There were a few minor confusing items in the tests, especially Test 7:

Test 1.
"Go to Users -> Users Action Logs
Filter by the 'Guided Tours' extension. The extension will NOT be in the list if there are no recorded logs yet."

• The part about "will NOT be in" is a bit confusing at this point, since we just created a Guided Tours event in configuration

Test 3.
"In the 'Basic settings' tab, select the option 'disallow' for the 'auto starting tours' parameter."

• the dropdown choice is "No"

Test 7.

• Kind of confusing instructions.
• Installed 5.1.2. Initial guided tour ran. X'ed out of that, and it would not run again. At least not anytime soon.
• Installed the update to 5.2.0-alpha4. Went to dashboard and initial guided tour did not run. But it was already not running in 5.1.2. Guided Tours is no longer selected as an item to log in User Action Logs per the desired outcome. Allow Auto Starting Tours is still Yes in global configuration for Guided Tours. Unlike before when we hit "Hide Forever" and there was a log entry of the event, now there's no way for an admin to know why that tour isn't running. Other than knowing this update will disable it.

  ---

  _{This comment was created with the J!Tracker Application at issues.joomla.org/tracker/joomla-cms/43814.}

[obuisard]

I have tested this item ✅ successfully on dfd42fcMarked successful because all the desired outcomes were achieved, I think.

Thank you!

There were a few minor confusing items in the tests, especially Test 7:

Test 1. "Go to Users -> Users Action Logs Filter by the 'Guided Tours' extension. The extension will NOT be in the list if there are no recorded logs yet."

• The part about "will NOT be in" is a bit confusing at this point, since we just created a Guided Tours event in configuration

It's just to instruct that if there is no 'Guided Tour' extension in the list of extensions, it means there are no logs for it.

Test 3. "In the 'Basic settings' tab, select the option 'disallow' for the 'auto starting tours' parameter."

• the dropdown choice is "No"

Yes, it changed recently, and I forgot to change the test description.

Test 7.

• Kind of confusing instructions.
• Installed 5.1.2. Initial guided tour ran. X'ed out of that, and it would not run again. At least not anytime soon.

Yes, that was the previous behavior.

• Installed the update to 5.2.0-alpha4. Went to dashboard and initial guided tour did not run. But it was already not running in 5.1.2. Guided Tours is no longer selected as an item to log in User Action Logs per the desired outcome.

That's because no tour was run.

Allow Auto Starting Tours is still Yes in global configuration for Guided Tours.
Unlike before when we hit "Hide Forever" and there was a log entry of the event, now there's no way for an admin to know why that tour isn't running.

The Welcome tour is not running because it is not set to auto start in 5.1. It was disabled after one run. It is an update, so the Welcome tour is not meant to run on update, only on new installs.

[webiedesign]

I have tested this item ✅ successfully on dfd42fc

I have tested this successfully

---

_{This comment was created with the J!Tracker Application at issues.joomla.org/tracker/joomla-cms/43814.}

[Quy]

RTC

---

_{This comment was created with the J!Tracker Application at issues.joomla.org/tracker/joomla-cms/43814.}

[Hackwar]

I'm merging this now, however I'm unhappy with the additional option in the user profile. Can we change this so that this option is only added to the profile when the site actually uses the tour feature? Maybe only inject it into the form when the system plugin is enabled?

In any case: Thank you for this contribution @obuisard

[Kostelano]

@obuisard

Very confusing wording. Could you please clarify what you are talking about? Perhaps rephrase it here in a simple way so that it can be translated correctly into other languages. Thank you.

COM_GUIDEDTOURS_USERSTATE_CONNECTEDONLY="Tour User state action is only for connected users."
COM_GUIDEDTOURS_USERSTATE_STATENOTSAVED="Tour User state not saved for user %1$s tour %2$s."
COM_GUIDEDTOURS_USERSTATE_STATESAVED="Tour User state saved for user %1$s tour %2$s."

[obuisard]

@obuisard

Very confusing wording. Could you please clarify what you are talking about? Perhaps rephrase it here in a simple way so that it can be translated correctly into other languages. Thank you.

COM_GUIDEDTOURS_USERSTATE_CONNECTEDONLY="Tour User state action is only for connected users."
COM_GUIDEDTOURS_USERSTATE_STATENOTSAVED="Tour User state not saved for user %1$s tour %2$s."
COM_GUIDEDTOURS_USERSTATE_STATESAVED="Tour User state saved for user %1$s tour %2$s."

Please check PR #44093. Thank you Konstantin @Kostelano