MDL-80871 tool_usertours: Allow tours to ignore completion

The use-case here is for tours which must be shown on every page load.

The tour still needs to be ended for the current page, but should be
shown again on the next time the page is loaded.

admin/tool/usertours/classes/external/tour.php

@@ -189,6 +189,7 @@ public static function complete_tour($tourid, $context, $pageurl, $stepid, $step
         self::validate_context($context);
 
         $tour = tourinstance::instance($params['tourid']);
+
         $tour->mark_user_completed();
 
         \tool_usertours\event\tour_ended::create([

admin/tool/usertours/classes/helper.php

@@ -21,9 +21,9 @@
 /**
  * Tour helper.
  *
- * @package    tool_usertours
  * @copyright  2016 Andrew Nicols <andrew@nicols.co.uk>
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package    tool_usertours
  */
 class helper {
     /**

admin/tool/usertours/classes/local/forms/edittour.php

@@ -29,6 +29,7 @@
 require_once($CFG->libdir . '/formslib.php');
 
 use tool_usertours\helper;
+use tool_usertours\tour;
 
 /**
  * Form for editing tours.
@@ -88,6 +89,17 @@ public function definition() {
         $mform->addElement('checkbox', 'displaystepnumbers', get_string('displaystepnumbers', 'tool_usertours'));
         $mform->addHelpButton('displaystepnumbers', 'displaystepnumbers', 'tool_usertours');
 
+        $mform->addElement(
+            'select',
+            'showtourwhen',
+            get_string('showtourwhen', 'tool_usertours'),
+            [
+                tour::SHOW_TOUR_UNTIL_COMPLETE => get_string('showtouruntilcomplete', 'tool_usertours'),
+                tour::SHOW_TOUR_ON_EACH_PAGE_VISIT => get_string('showtoureachtime', 'tool_usertours'),
+            ]
+        );
+        $mform->setDefault('showtourwhen', tour::SHOW_TOUR_UNTIL_COMPLETE);
+
         // Configuration.
         $this->tour->add_config_to_form($mform);
 

admin/tool/usertours/classes/manager.php

@@ -363,6 +363,7 @@ protected function edit_tour($id = null) {
             $tour->set_enabled(!empty($data->enabled));
             $tour->set_endtourlabel($data->endtourlabel);
             $tour->set_display_step_numbers(!empty($data->displaystepnumbers));
+            $tour->set_showtourwhen($data->showtourwhen);
 
             foreach (configuration::get_defaultable_keys() as $key) {
                 $tour->set_config($key, $data->$key);

admin/tool/usertours/classes/tour.php

@@ -52,6 +52,12 @@ class tour {
      */
     const TOUR_REQUESTED_BY_USER        = 'tool_usertours_tour_reset_time_';
 
+    /** @var int Whether to show the tour only until it has been marked complete */
+    const SHOW_TOUR_UNTIL_COMPLETE = 1;
+
+    /** @var int Whether to show the tour every time a page matches */
+    const SHOW_TOUR_ON_EACH_PAGE_VISIT = 2;
+
     /**
      * @var $id The tour ID.
      */
@@ -641,6 +647,11 @@ public function should_show_for_user() {
             return false;
         }
 
+        if ($this->get_showtourwhen() === self::SHOW_TOUR_ON_EACH_PAGE_VISIT) {
+            // The tour should be shown on every page visit.
+            return true;
+        }
+
         if ($tourcompletiondate = get_user_preferences(self::TOUR_LAST_COMPLETED_BY_USER . $this->get_id(), null)) {
             if ($tourresetdate = get_user_preferences(self::TOUR_REQUESTED_BY_USER . $this->get_id(), null)) {
                 if ($tourresetdate >= $tourcompletiondate) {
@@ -763,6 +774,7 @@ protected function add_config_field_to_form(\MoodleQuickForm &$mform, $key) {
      */
     public function prepare_data_for_form() {
         $data = $this->to_record();
+        $data->showtourwhen = $this->get_showtourwhen();
         foreach (configuration::get_defaultable_keys() as $key) {
             $data->$key = $this->get_config($key, configuration::get_default_value($key));
         }
@@ -860,4 +872,29 @@ public function set_display_step_numbers(bool $value): tour {
     public function get_display_step_numbers(): bool {
         return $this->displaystepnumbers;
     }
+
+    /**
+     * Set the value for the when to show the tour.
+     *
+     * @see self::SHOW_TOUR_UNTIL_COMPLETE
+     * @see self::SHOW_TOUR_ON_EACH_PAGE_VISIT
+     *
+     * @param int $value
+     * @return self
+     */
+    public function set_showtourwhen(int $value): tour {
+        return $this->set_config('showtourwhen', $value);
+    }
+
+    /**
+     * When to show the tour.
+     *
+     * @see self::SHOW_TOUR_UNTIL_COMPLETE
+     * @see self::SHOW_TOUR_ON_EACH_PAGE_VISIT
+     *
+     * @return int
+     */
+    public function get_showtourwhen(): int {
+        return $this->get_config('showtourwhen', self::SHOW_TOUR_UNTIL_COMPLETE);
+    }
 }

admin/tool/usertours/lang/en/tool_usertours.php

@@ -36,6 +36,9 @@
 Alternatively, a language string ID may be entered in the format identifier,component (with no brackets or space after the comma).';
 $string['displaystepnumbers'] = 'Display step numbers';
 $string['displaystepnumbers_help'] = 'Whether to display a step number count e.g. 1/4, 2/4 etc. to indicate the length of the user tour.';
+$string['showtourwhen'] = 'Show tour';
+$string['showtoureachtime'] = 'each time a filter matches it';
+$string['showtouruntilcomplete'] = 'until it has been closed';
 $string['confirmstepremovalquestion'] = 'Are you sure that you wish to remove this step?';
 $string['confirmstepremovaltitle'] = 'Confirm step removal';
 $string['confirmtourremovalquestion'] = 'Are you sure that you wish to remove this tour?';

admin/tool/usertours/tests/behat/tour_prevents_completion.feature

@@ -0,0 +1,29 @@
+@tool @tool_usertours
+Feature: Prevent yours from being marked as complete
+    In order to impart key information
+    As an administrator
+    I can prevent a user tour from being marked as complete
+
+  Background:
+    Given I log in as "admin"
+    And I add a new user tour with:
+      | Name               | First tour    |
+      | Description        | My first tour |
+      | Apply to URL match | FRONTPAGE     |
+      | Tour is enabled    | 1             |
+      | Show with backdrop | 1             |
+      # 2 = tour::SHOW_TOUR_ON_EACH_PAGE_VISIT
+      | Show tour | 2 |
+    And I add steps to the "First tour" tour:
+      | targettype                | Title   | id_content    | Content type |
+      | Display in middle of page | Welcome | Welcome tour. | Manual       |
+
+  @javascript
+  Scenario: Ending the tour should not mark it as complete
+    # Changing the window viewport to mobile so we will have the footer section.
+    Given I am on site homepage
+    And I should see "Welcome"
+    And I press "Got it"
+    And I should not see "Welcome"
+    When I am on site homepage
+    Then I should see "Welcome"

admin/tool/usertours/tests/tour_test.php

@@ -98,6 +98,10 @@ public static function dirty_value_provider(): array {
                 'config',
                 ['key', 'value'],
             ],
+            'showtourwhen' => [
+                'showtourwhen',
+                [0],
+            ],
         ];
     }
 
@@ -598,30 +602,44 @@ public static function should_show_for_user_provider(): array {
                 null,
                 null,
                 null,
+                [],
                 true,
             ],
             'Completed by user before majorupdatetime' => [
                 $time - DAYSECS,
                 null,
                 $time,
+                [],
                 true,
             ],
             'Completed by user since majorupdatetime' => [
                 $time,
                 null,
                 $time - DAYSECS,
+                [],
                 false,
             ],
             'Requested by user before current completion' => [
                 $time,
                 $time - DAYSECS,
-                null,
+                $time - MINSECS,
+                [],
                 false,
             ],
             'Requested by user since completion' => [
                 $time - DAYSECS,
                 $time,
+                'null',
+                [],
+                true,
+            ],
+            'Tour will show on each load' => [
+                $time,
+                $time - DAYSECS,
                 null,
+                [
+                    'showtourwhen' => tour::SHOW_TOUR_ON_EACH_PAGE_VISIT,
+                ],
                 true,
             ],
         ];
@@ -634,24 +652,34 @@ public static function should_show_for_user_provider(): array {
      * @param   mixed   $completiondate The user's completion date for this tour
      * @param   mixed   $requesteddate  The user's last requested date for this tour
      * @param   mixed   $updateddate    The date this tour was last updated
+     * @param   mixed   $config         The tour config to apply
      * @param   string  $expectation    The expected tour key
      */
-    public function test_should_show_for_user($completiondate, $requesteddate, $updateddate, $expectation): void {
+    public function test_should_show_for_user(
+        $completiondate,
+        $requesteddate,
+        $updateddate,
+        $config,
+        $expectation,
+    ): void {
         // Uses user preferences so we must be in a user context.
         $this->resetAfterTest();
         $this->setAdminUser();
 
         $tour = $this->getMockBuilder(tour::class)
             ->onlyMethods([
                 'get_id',
-                'get_config',
                 'is_enabled',
             ])
             ->getMock();
 
         $tour->method('is_enabled')
             ->willReturn(true);
 
+        foreach ($config as $key => $value) {
+            $tour->set_config($key, $value);
+        }
+
         $id = rand(1, 100);
         $tour->method('get_id')
             ->willReturn($id);
@@ -665,9 +693,7 @@ public function test_should_show_for_user($completiondate, $requesteddate, $upda
         }
 
         if ($updateddate !== null) {
-            $tour->expects($this->once())
-                ->method('get_config')
-                ->willReturn($updateddate);
+            $tour->set_config('majorupdatetime', $updateddate);
         }
 
         $this->assertEquals($expectation, $tour->should_show_for_user());