Proyectos de Subversion Moodle

<?php

// This file is part of Moodle - http://moodle.org/

//

// Moodle is free software: you can redistribute it and/or modify

// it under the terms of the GNU General Public License as published by

// the Free Software Foundation, either version 3 of the License, or

// (at your option) any later version.

//

// Moodle is distributed in the hope that it will be useful,

// but WITHOUT ANY WARRANTY; without even the implied warranty of

// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

// GNU General Public License for more details.

//

// You should have received a copy of the GNU General Public License

// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

namespace tool_usertours;

/**

 * Tour class.

 *

 * @package    tool_usertours

 * @copyright  2016 Andrew Nicols <andrew@nicols.co.uk>

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

class tour {

    /**

     * The tour is currently disabled

     *

     * @var DISABLED

     */

    const DISABLED = 0;

    /**

     * The tour is currently disabled

     *

     * @var DISABLED

     */

    const ENABLED = 1;

    /**

     * The user preference value to indicate the time of completion of the tour for a user.

     *

     * @var TOUR_LAST_COMPLETED_BY_USER

     */

    const TOUR_LAST_COMPLETED_BY_USER   = 'tool_usertours_tour_completion_time_';

    /**

     * The user preference value to indicate the time that a user last requested to see the tour.

     *

     * @var TOUR_REQUESTED_BY_USER

     */

    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.

     */

    protected $id;

    /**

     * @var $name The tour name.

     */

    protected $name;

    /**

     * @var $description The tour description.

     */

    protected $description;

    /**

     * @var $pathmatch The tour pathmatch.

     */

    protected $pathmatch;

    /**

     * @var $enabled The tour enabled state.

     */

    protected $enabled;

    /**

     * @var $endtourlabel The end tour label.

     */

    protected $endtourlabel;

    /**

     * @var $sortorder The sort order.

     */

    protected $sortorder;

    /**

     * @var $dirty Whether the current view of the tour has been modified.

     */

    protected $dirty = false;

    /**

     * @var $config The configuration object for the tour.

     */

    protected $config;

    /**

     * @var $filtervalues The filter configuration object for the tour.

     */

    protected $filtervalues;

    /**

     * @var $steps  The steps in this tour.

     */

    protected $steps = [];

    /**

     * @var bool $displaystepnumbers Display the step numbers in this tour.

     */

    protected $displaystepnumbers = true;

    /**

     * Create an instance of the specified tour.

     *

     * @param   int         $id         The ID of the tour to load.

     * @return  tour

     */

    public static function instance($id) {

        $tour = new self();

        return $tour->fetch($id);

    }

    /**

     * Create an instance of tour from its provided DB record.

     *

     * @param   stdClass    $record     The record of the tour to load.

     * @param   boolean     $clean      Clean the values.

     * @return  tour

     */

    public static function load_from_record($record, $clean = false) {

        $tour = new self();

        return $tour->reload_from_record($record, $clean);

    }

    /**

     * Fetch the specified tour into the current object.

     *

     * @param   int         $id         The ID of the tour to fetch.

     * @return  tour

     */

    protected function fetch($id) {

        global $DB;

        return $this->reload_from_record(

            $DB->get_record('tool_usertours_tours', ['id' => $id], '*', MUST_EXIST)

        );

    }

    /**

     * Reload the current tour from database.

     *

     * @return  tour

     */

    protected function reload() {

        return $this->fetch($this->id);

    }

    /**

     * Reload the tour into the current object.

     *

     * @param   stdClass    $record     The record to reload.

     * @param   boolean     $clean      Clean the values.

     * @return  tour

     */

    protected function reload_from_record($record, $clean = false) {

        $this->id           = $record->id;

        if (!property_exists($record, 'description')) {

            if (property_exists($record, 'comment')) {

                $record->description = $record->comment;

                unset($record->comment);

            }

        }

        if ($clean) {

            $this->name         = clean_param($record->name, PARAM_TEXT);

            $this->description  = clean_text($record->description);

        } else {

            $this->name         = $record->name;

            $this->description  = $record->description;

        }

        $this->pathmatch    = $record->pathmatch;

        $this->enabled      = $record->enabled;

        if (isset($record->sortorder)) {

            $this->sortorder = $record->sortorder;

        }

        $this->endtourlabel = $record->endtourlabel ?? null;

        $this->config       = json_decode($record->configdata);

        $this->dirty        = false;

        $this->steps        = [];

        $this->displaystepnumbers = !empty($record->displaystepnumbers);

        return $this;

    }

    /**

     * Fetch all steps in the tour.

     *

     * @return  step[]

     */

    public function get_steps() {

        if (empty($this->steps)) {

            $this->steps = helper::get_steps($this->id);

        }

        return $this->steps;

    }

    /**

     * Count the number of steps in the tour.

     *

     * @return  int

     */

    public function count_steps() {

        return count($this->get_steps());

    }

    /**

     * The ID of the tour.

     *

     * @return  int

     */

    public function get_id() {

        return $this->id;

    }

    /**

     * The name of the tour.

     *

     * @return  string

     */

    public function get_name() {

        return $this->name;

    }

    /**

     * Set the name of the tour to the specified value.

     *

     * @param   string      $value      The new name.

     * @return  $this

     */

    public function set_name($value) {

        $this->name = clean_param($value, PARAM_TEXT);

        $this->dirty = true;

        return $this;

    }

    /**

     * The description associated with the tour.

     *

     * @return  string

     */

    public function get_description() {

        return $this->description;

    }

    /**

     * Set the description of the tour to the specified value.

     *

     * @param   string      $value      The new description.

     * @return  $this

     */

    public function set_description($value) {

        $this->description = clean_text($value);

        $this->dirty = true;

        return $this;

    }

    /**

     * The path match for the tour.

     *

     * @return  string

     */

    public function get_pathmatch() {

        return $this->pathmatch;

    }

    /**

     * Set the patchmatch of the tour to the specified value.

     *

     * @param   string      $value      The new patchmatch.

     * @return  $this

     */

    public function set_pathmatch($value) {

        $this->pathmatch = $value;

        $this->dirty = true;

        return $this;

    }

    /**

     * The enabled state of the tour.

     *

     * @return  int

     */

    public function get_enabled() {

        return $this->enabled;

    }

    /**

     * Whether the tour is currently enabled.

     *

     * @return  boolean

     */

    public function is_enabled() {

        return ($this->enabled == self::ENABLED);

    }

    /**

     * Set the enabled state of the tour to the specified value.

     *

     * @param   boolean     $value      The new state.

     * @return  $this

     */

    public function set_enabled($value) {

        $this->enabled = $value;

        $this->dirty = true;

        return $this;

    }

    /**

     * The end tour label for the tour.

     *

     * @return string

     */

    public function get_endtourlabel(): string {

        if ($this->endtourlabel) {

            $label = helper::get_string_from_input($this->endtourlabel);

        } else if ($this->count_steps() == 1) {

            $label = get_string('endonesteptour', 'tool_usertours');

        } else {

            $label = get_string('endtour', 'tool_usertours');

        }

        return $label;

    }

    /**

     * Set the endtourlabel of the tour to the specified value.

     *

     * @param string $value

     * @return $this

     */

    public function set_endtourlabel(string $value): tour {

        $this->endtourlabel = $value;

        $this->dirty = true;

        return $this;

    }

    /**

     * The link to view this tour.

     *

     * @return  \moodle_url

     */

    public function get_view_link() {

        return helper::get_view_tour_link($this->id);

    }

    /**

     * The link to edit this tour.

     *

     * @return  \moodle_url

     */

    public function get_edit_link() {

        return helper::get_edit_tour_link($this->id);

    }

    /**

     * The link to reset the state of this tour for all users.

     *

     * @return  moodle_url

     */

    public function get_reset_link() {

        return helper::get_reset_tour_for_all_link($this->id);

    }

    /**

     * The link to export this tour.

     *

     * @return  moodle_url

     */

    public function get_export_link() {

        return helper::get_export_tour_link($this->id);

    }

    /**

     * The link to duplicate this tour.

     *

     * @return  moodle_url

     */

    public function get_duplicate_link() {

        return helper::get_duplicate_tour_link($this->id);

    }

    /**

     * The link to remove this tour.

     *

     * @return  moodle_url

     */

    public function get_delete_link() {

        return helper::get_delete_tour_link($this->id);

    }

    /**

     * Prepare this tour for saving to the database.

     *

     * @return  object

     */

    public function to_record() {

        return (object) [

            'id'            => $this->id,

            'name'          => $this->name,

            'description'   => $this->description,

            'pathmatch'     => $this->pathmatch,

            'enabled'       => $this->enabled,

            'sortorder'     => $this->sortorder,

            'endtourlabel'  => $this->endtourlabel,

            'configdata'    => json_encode($this->config),

            'displaystepnumbers' => $this->displaystepnumbers,

        ];

    }

    /**

     * Get the current sortorder for this tour.

     *

     * @return  int

     */

    public function get_sortorder() {

        return (int) $this->sortorder;

    }

    /**

     * Whether this tour is the first tour.

     *

     * @return  boolean

     */

    public function is_first_tour() {

        return ($this->get_sortorder() === 0);

    }

    /**

     * Whether this tour is the last tour.

     *

     * @param   int         $tourcount  The pre-fetched count of tours

     * @return  boolean

     */

    public function is_last_tour($tourcount = null) {

        if ($tourcount === null) {

            $tourcount = helper::count_tours();

        }

        return ($this->get_sortorder() === ($tourcount - 1));

    }

    /**

     * Set the sortorder for this tour.

     *

     * @param   int         $value      The new sortorder to use.

     * @return  $this

     */

    public function set_sortorder($value) {

        $this->sortorder = $value;

        $this->dirty = true;

        return $this;

    }

    /**

     * Calculate the next sort-order value.

     *

     * @return  int

     */

    protected function calculate_sortorder() {

        $this->sortorder = helper::count_tours();

        return $this;

    }

    /**

     * Get the link to move this tour up in the sortorder.

     *

     * @return  moodle_url

     */

    public function get_moveup_link() {

        return helper::get_move_tour_link($this->get_id(), helper::MOVE_UP);

    }

    /**

     * Get the link to move this tour down in the sortorder.

     *

     * @return  moodle_url

     */

    public function get_movedown_link() {

        return helper::get_move_tour_link($this->get_id(), helper::MOVE_DOWN);

    }

    /**

     * Get the value of the specified configuration item.

     *

     * @param   string      $key        The configuration key to set.

     * @param   mixed       $default    The default value to use if a value was not found.

     * @return  mixed

     */

    public function get_config($key = null, $default = null) {

        if ($this->config === null) {

            $this->config = (object) [];

        }

        if ($key === null) {

            return $this->config;

        }

        if (property_exists($this->config, $key)) {

            return $this->config->$key;

        }

        if ($default !== null) {

            return $default;

        }

        return configuration::get_default_value($key);

    }

    /**

     * Set the configuration item as specified.

     *

     * @param   string      $key        The configuration key to set.

     * @param   mixed       $value      The new value for the configuration item.

     * @return  $this

     */

    public function set_config($key, $value) {

        if ($this->config === null) {

            $this->config = (object) [];

        }

        $this->config->$key = $value;

        $this->dirty = true;

        return $this;

    }

    /**

     * Save the tour and it's configuration to the database.

     *

     * @param   boolean     $force      Whether to force writing to the database.

     * @return  $this

     */

    public function persist($force = false) {

        global $DB;

        if (!$this->dirty && !$force) {

            return $this;

        }

        if ($this->id) {

            $record = $this->to_record();

            $DB->update_record('tool_usertours_tours', $record);

        } else {

            $this->calculate_sortorder();

            $record = $this->to_record();

            unset($record->id);

            $this->id = $DB->insert_record('tool_usertours_tours', $record);

        }

        $this->reload();

        // Notify the cache that a tour has changed.

        cache::notify_tour_change();

        return $this;

    }

    /**

     * Remove this step.

     */

    public function remove() {

        global $DB;

        if ($this->id === null) {

            // Nothing to delete - this tour has not been persisted.

            return null;

        }

        // Delete all steps associated with this tour.

        // Note, although they are currently just DB records, there may be other components in the future.

        foreach ($this->get_steps() as $step) {

            $step->remove();

        }

        // Remove the configuration for the tour.

        $DB->delete_records('tool_usertours_tours', ['id' => $this->id]);

        helper::reset_tour_sortorder();

        $this->remove_user_preferences();

        return null;

    }

    /**

     * Reset the sortorder for all steps in the tour.

     *

     * @return  $this

     */

    public function reset_step_sortorder() {

        global $DB;

        $steps = $DB->get_records('tool_usertours_steps', ['tourid' => $this->id], 'sortorder ASC', 'id');

        $index = 0;

        foreach ($steps as $step) {

            $DB->set_field('tool_usertours_steps', 'sortorder', $index, ['id' => $step->id]);

            $index++;

        }

        // Notify of a change to the step configuration.

        // Note: Do not notify of a tour change here. This is only a step change for a tour.

        cache::notify_step_change($this->get_id());

        return $this;

    }

    /**

     * Remove stored user preferences for the tour

     */

    protected function remove_user_preferences(): void {

        global $DB;

        $DB->delete_records('user_preferences', ['name' => self::TOUR_LAST_COMPLETED_BY_USER . $this->get_id()]);

        $DB->delete_records('user_preferences', ['name' => self::TOUR_REQUESTED_BY_USER . $this->get_id()]);

    }

    /**

     * Whether this tour should be displayed to the user.

     *

     * @return  boolean

     */

    public function should_show_for_user() {

        if (!$this->is_enabled()) {

            // The tour is disabled - it should not be shown.

            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) {

                    return true;

                }

            }

            $lastmajorupdate = $this->get_config('majorupdatetime', time());

            if ($tourcompletiondate > $lastmajorupdate) {

                // The user has completed the tour since the last major update.

                return false;

            }

        }

        return true;

    }

    /**

     * Get the key for this tour.

     * This is used in the session cookie to determine whether the user has seen this tour before.

     */

    public function get_tour_key() {

        global $USER;

        $tourtime = $this->get_config('majorupdatetime', null);

        if ($tourtime === null) {

            // This tour has no majorupdate time.

            // Set one now to prevent repeated displays to the user.

            $this->set_config('majorupdatetime', time());

            $this->persist();

            $tourtime = $this->get_config('majorupdatetime', null);

        }

        if ($userresetdate = get_user_preferences(self::TOUR_REQUESTED_BY_USER . $this->get_id(), null)) {

            $tourtime = max($tourtime, $userresetdate);

        }

        return sprintf('tool_usertours_%d_%d_%s', $USER->id, $this->get_id(), $tourtime);

    }

    /**

     * Reset the requested by user date.

     *

     * @return  $this

     */

    public function request_user_reset() {

        set_user_preference(self::TOUR_REQUESTED_BY_USER . $this->get_id(), time());

        return $this;

    }

    /**

     * Mark this tour as completed for this user.

     *

     * @return  $this

     */

    public function mark_user_completed() {

        set_user_preference(self::TOUR_LAST_COMPLETED_BY_USER . $this->get_id(), time());

        return $this;

    }

    /**

     * Update a tour giving it a new major update time.

     * This will ensure that it is displayed to all users, even those who have already seen it.

     *

     * @return  $this

     */

    public function mark_major_change() {

        // Clear old reset and completion notes.

        $this->remove_user_preferences();

        $this->set_config('majorupdatetime', time());

        $this->persist();

        return $this;

    }

    /**

     * Add the step configuration to the form.

     *

     * @param   MoodleQuickForm $mform      The form to add configuration to.

     * @return  $this

     */

    public function add_config_to_form(\MoodleQuickForm &$mform) {

        $options = configuration::get_placement_options();

        $mform->addElement('select', 'placement', get_string('placement', 'tool_usertours'), $options);

        $mform->addHelpButton('placement', 'placement', 'tool_usertours');

        $this->add_config_field_to_form($mform, 'orphan');

        $this->add_config_field_to_form($mform, 'backdrop');

        $this->add_config_field_to_form($mform, 'reflex');

        return $this;

    }

    /**

     * Add the specified step field configuration to the form.

     *

     * @param   MoodleQuickForm $mform      The form to add configuration to.

     * @param   string          $key        The key to add.

     * @return  $this

     */

    protected function add_config_field_to_form(\MoodleQuickForm &$mform, $key) {

        $options = [

            true    => get_string('yes'),

            false   => get_string('no'),

        ];

        $mform->addElement('select', $key, get_string($key, 'tool_usertours'), $options);

        $mform->setDefault($key, configuration::get_default_value($key));

        $mform->addHelpButton($key, $key, 'tool_usertours');

        return $this;

    }

    /**

     * Prepare the configuration data for the moodle form.

     *

     * @return  object

     */

    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));

        }

        return $data;

    }

    /**

     * Get the configured filter values.

     *

     * @param   string      $filter     The filter to retrieve values for.

     * @return  array

     */

    public function get_filter_values($filter) {

        if ($allvalues = (array) $this->get_config('filtervalues')) {

            if (isset($allvalues[$filter])) {

                return $allvalues[$filter];

            }

        }

        return [];

    }

    /**

     * Set the values for the specified filter.

     *

     * @param   string      $filter     The filter to set.

     * @param   array       $values     The values to set.

     * @return  $this

     */

    public function set_filter_values($filter, array $values = []) {

        $allvalues = (array) $this->get_config('filtervalues', []);

        $allvalues[$filter] = $values;

        return $this->set_config('filtervalues', $allvalues);

    }

    /**

     * Check whether this tour matches all filters.

     *

     * @param   \context     $context    The context to check.

     * @param   array|null   $filters    Optional array of filters.

     * @return  bool

     */

    public function matches_all_filters(\context $context, array $filters = null): bool {

        if (!$filters) {

            $filters = helper::get_all_filters();

        }

        // All filters must match.

        // If any one filter fails to match, we return false.

        foreach ($filters as $filterclass) {

            if (!$filterclass::filter_matches($this, $context)) {

                return false;

            }

        }

        return true;

    }

    /**

     * Gets all filter values for use in client side filters.

     *

     * @param   array     $filters    Array of clientside filters.

     * @return  array

     */

    public function get_client_filter_values(array $filters): array {

        $results = [];

        foreach ($filters as $filter) {

            $results[$filter::get_filter_name()] = $filter::get_client_side_values($this);

        }

        return $results;

    }

    /**

     * Set the value for the display step numbers setting.

     *

     * @param bool $value True for enable.

     * @return $this

     */

    public function set_display_step_numbers(bool $value): tour {

        $this->displaystepnumbers = $value;

        $this->dirty = true;

        return $this;

    }

    /**

     * Get the value of the display step numbers setting.

     *

     * @return bool

     */

    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);

    }

}