[#43814] - [5.2] [Guided tours] Auto start tours - full functionality
- Fixed in Code Base
- 30 Aug 2024
- Medium
- Build: 5.2-dev
- # 43814
- Diff
- obuisard:guided-tours-autostart
- Pending continuous-integration/drone/pr Build is pending Details
User tests: Successful: Unsuccessful:
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 #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.
| Status | New | ⇒ | Pending |
joomla-cms-bot
- | Category | ⇒ | SQL Administration com_admin Postgresql com_users Language & Strings JavaScript Repository NPM Change Front End Plugins |
| Labels |
Added:
Language Change
NPM Resource Changed
PR-5.2-dev
|
||
| Category | SQL Administration com_admin Postgresql com_users Language & Strings JavaScript Repository NPM Change Front End Plugins | ⇒ | Administration SQL com_admin Postgresql com_users Language & Strings JavaScript Repository NPM Change Front End Installation Plugins |
| Category | SQL Administration com_admin Postgresql com_users Language & Strings JavaScript Repository NPM Change Front End Plugins Installation | ⇒ | Administration SQL com_admin Postgresql com_users Language & Strings JavaScript Repository NPM Change Front End Installation Plugins Unit Tests |
| Labels |
Added:
Unit/System Tests
|
||
On a new instance of Joomla, the Guided Tours action logs are enabled by default.
I forgot to add a database entry into #__action_log_config.
I forgot to add a database entry into #__action_log_config.
It is still not enabled by default with the latest commits per the built-in package.
It is still not enabled by default with the latest commits per the built-in package.
It is fixed, I needed to add com_guidedtours to base.sql in the installation folder.
I have tested this item ? unsuccessfully on dfd42fc
I used the full install package.
Not truly an unsuccessful test because almost everything major worked like they were supposed to, but some minor things didn't work like the directions said.
Test 1
"Go to Users -> Users Action Logs
Filter by the 'Guided Tours' extension."
- ** there was no such filter option. That I could find anyhow. Only available were Users and Configuration. Anything I did to Tours got marked as extension Configuration in the logs, also. **
Test 4
"Go to Users -> Users Action Logs
Filter by the 'Guided Tours' extension."
– again no such filter option
"You should see User [you] skipped the tour 'Welcome to Joomla!'."
– ** did not see this, only that I updated the user, and prior to that that I had changed settings of the application configuration **.
Test 5
"If the tour is not completed and it had been cancelled before (neither skipped nor completed), it will auto-start after the delay set in the global configuration."
- ** I must have misunderstood these directions. Interrupted the manually started tour after two steps with the X option. The interrupted tour did not ever autorestart after that, and I am unclear why it should have at all, since it had been "hidden forever" in Step 4 **.
This comment was created with the J!Tracker Application at issues.joomla.org/tracker/joomla-cms/43814.
Thanks you for testing @terryburg !
I have tested this item ? unsuccessfully on dfd42fcI used the full install package.
I am afraid this is not the latest version available. Major changes have been made after I discovered changes to the User Action Logs plugin today. Plus, the user action logs were not set by default on install.
Not truly an unsuccessful test because almost everything major worked like they were supposed to, but some minor things didn't work like the directions said.
Test 1 "Go to Users -> Users Action Logs Filter by the 'Guided Tours' extension."
- ** there was no such filter option. That I could find anyhow. Only available were Users and Configuration. Anything I did to Tours got marked as extension Configuration in the logs, also. **
There is no 'Guided Tours' selection in the filter until there are recorded user action logs for it (I have now added such a comment in the test instructions).
You did not have the option to select 'Guided Tours', therefore there was no action log recorded.
Action logs were broken until I made corrections to the code to fix it.
Test 4 "Go to Users -> Users Action Logs Filter by the 'Guided Tours' extension." – again no such filter option "You should see User [you] skipped the tour 'Welcome to Joomla!'." – ** did not see this, only that I updated the user, and prior to that that I had changed settings of the application configuration **.
Same thing, action logs were broken therefore no user action log about guided tours has been recorded.
Test 5 "If the tour is not completed and it had been cancelled before (neither skipped nor completed), it will auto-start after the delay set in the global configuration."
- ** I must have misunderstood these directions. Interrupted the manually started tour after two steps with the X option. The interrupted tour did not ever autorestart after that, and I am unclear why it should have at all, since it had been "hidden forever" in Step 4 **.
Yes, my explanations were not needed here, I am going to fix my comment.
You created several event triggers, all of them need own event classes and need to be created directly.
Also I'm wondering why you call 2 events directly behind each other.
The code in the controller changing the dB should be in the model.
I only did a quick check on the phone so maybe I missed something.
Addidionaly to @HLeithner comments.
Please reduce amount of events, I mean, we always can added them later wheen needed.
From what I see there only one event is in use onTourRunSaveState,
So I would suggest to keep only 2 event, but name: onBeforeTourSaveUserState and onAfterTourSaveUserState (it more reflect what is going on). (The name onTourRunSaveState a bit confusing to me)
Addidionaly to @HLeithner comments. Please reduce amount of events, I mean, we always can added them later wheen needed. From what I see there only one event is in use
onTourRunSaveState,So I would suggest to keep only 2 event, but name:
onBeforeTourSaveUserStateandonAfterTourSaveUserState(it more reflect what is going on). (The nameonTourRunSaveStatea bit confusing to me)
I have removed the onTourRunSaveState. Now, the user action logs are created on onBeforeTourSaveUserState.
onAfterTourSaveUserState is available to later on provide feedback to user and trigger additional actions.
The code in the controller changing the dB should be in the model.
I moved the controller's database calls to the tour model.
You've made changes to the cypress tests here but you havent updated the joomla-cypress package
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
and then you need to update your branch to use that - ie npm update joomla-cyprus
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.
| Category | SQL Administration com_admin Postgresql com_users Language & Strings JavaScript Repository NPM Change Front End Plugins Installation Unit Tests | ⇒ | Administration SQL com_admin Postgresql com_users Language & Strings JavaScript Repository NPM Change Front End Installation Plugins |
| Labels |
Removed:
Unit/System Tests
|
||
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
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!
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.
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.
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.
| Status | Pending | ⇒ | Ready to Commit |
RTC
This comment was created with the J!Tracker Application at issues.joomla.org/tracker/joomla-cms/43814.
| Labels |
Added:
RTC
|
||
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
| Status | Ready to Commit | ⇒ | Fixed in Code Base |
| Closed_Date | 0000-00-00 00:00:00 | ⇒ | 2024-08-30 21:07:24 |
| Closed_By | ⇒ | Hackwar |
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."
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
This is not the case.
