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

use core_customfield\data_controller;

use core_customfield\field_controller;

use tool_courserating\external\stars_exporter;

/**

 * Additional helper functions

 *

 * @package     tool_courserating

 * @copyright   2022 Marina Glancy <marina.glancy@gmail.com>

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

 */

class helper {

    /**

     * Temporary function

     *

     * @return void

     */

    private function wordings() {

        // @codingStandardsIgnoreStart

        // Udemy.

        'You\'ve finished the last lesson in this course! Would you like to leave a review?';

        [

            1 => 'Awful, not what I was expecting at all',

            1.5 => 'Awful / Poor',

            2 => 'Poor, pretty disappointed',

            2.5 => 'Poor / Average',

            3 => 'Average, could be better',

            3.5 => 'Average / Good',

            4 => 'Good, what I expected',

            4.5 => 'Good / Amazing',

            5 => 'Amazing, above expectations',

        ];

        'Tell us about your own personal experience taking this course. Was it a good match for you?';

        'Report'; 'Report abuse';

        'Flagged content is reviewed by Udemy staff to determine whether it violates Terms of Service or Community Guidelines. If you have a question or technical issue, please contact our Support team here.';

        'Issue type';

        [

            'Inappropriate Course Content',

            'Inappropriate Behavior',

            'Udemy Policy Violation',

            'Spammy Content',

            'Other',

        ];

        'Issue details';

        // @codingStandardsIgnoreEnd

    }

    /**

     * Checks if we are on a main course page

     *

     * @return int

     */

    public static function is_course_page(): int {

        global $PAGE, $CFG;

        if ($PAGE->course && $PAGE->url->out_omit_querystring() === $CFG->wwwroot . '/course/view.php') {

            return $PAGE->course->id;

        }

        return 0;

    }

    /**

     * Checks if we are on a main page of single-activity course

     *

     * @return int

     */

    public static function is_single_activity_course_page(): int {

        global $PAGE, $CFG;

        if ($PAGE->context->contextlevel == CONTEXT_MODULE && $PAGE->course->format === 'singleactivity' &&

            $PAGE->url->out_omit_querystring() === $CFG->wwwroot . '/mod/' . $PAGE->cm->modname . '/view.php') {

            return $PAGE->course->id;

        }

        return 0;

    }

    /**

     * Checks if we are on a course edit page

     *

     * @return int

     */

    public static function is_course_edit_page(): int {

        global $PAGE, $CFG;

        if ($PAGE->course && $PAGE->url->out_omit_querystring() === $CFG->wwwroot . '/course/edit.php') {

            return $PAGE->course->id;

        }

        return 0;

    }

    /**

     * Are course ratings enabled (or could be enabled) in any courses? Do we need to have a course rating field

     *

     * @return bool

     */

    public static function course_ratings_enabled_anywhere(): bool {

        if (self::get_setting(constants::SETTING_RATINGMODE) == constants::RATEBY_NOONE &&

                !self::get_setting(constants::SETTING_PERCOURSE)) {

            return false;

        }

        return true;

    }

    /**

     * Options for the review editor form element

     *

     * @param \context $context

     * @return array

     */

    public static function review_editor_options(\context $context) {

        global $CFG;

        require_once($CFG->dirroot.'/lib/formslib.php');

        return [

            'subdirs' => 0,

            'maxbytes' => $CFG->maxbytes,

            'maxfiles' => EDITOR_UNLIMITED_FILES,

            'changeformat' => 0,

            'context' => $context,

        ];

    }

    /**

     * Retrieve and clean plugin setting

     *

     * @param string $name

     * @return bool|mixed|object|string

     */

    public static function get_setting(string $name) {

        $value = get_config('tool_courserating', $name);

        static $defaults = [

            constants::SETTING_STARCOLOR => constants::SETTING_STARCOLOR_DEFAULT,

            constants::SETTING_RATINGCOLOR => constants::SETTING_RATINGCOLOR_DEFAULT,

            constants::SETTING_DISPLAYEMPTY => false,

            constants::SETTING_PERCOURSE => false,

            constants::SETTING_RATINGMODE => constants::RATEBY_ANYTIME,

            constants::SETTING_USEHTML => false,

        ];

        if (!isset($value) && array_key_exists($name, $defaults)) {

            // Can only happen if there is unfinished upgrade.

            return $defaults[$name];

        }

        if ($name === constants::SETTING_DISPLAYEMPTY || $name === constants::SETTING_PERCOURSE

                || $name === constants::SETTING_USEHTML) {

            return !empty($value);

        }

        if ($name === constants::SETTING_STARCOLOR || $name === constants::SETTING_RATINGCOLOR) {

            $color = strtolower($value ?? '');

            return (preg_match('/^#[a-f0-9]{6}$/', $color)) ? $color : $defaults[$name];

        }

        if ($name === constants::SETTING_RATINGMODE) {

            static $available = [constants::RATEBY_NOONE, constants::RATEBY_ANYTIME, constants::RATEBY_COMPLETED];

            return in_array($value, $available) ? $value : $defaults[$name];

        }

        return $value;

    }

    /**

     * CSS for the stars colors to be added to the page

     *

     * @return string

     */

    public static function get_rating_colour_css() {

        return '.tool_courserating-stars { color: '.self::get_setting(constants::SETTING_STARCOLOR).'; }'."\n".

            '.tool_courserating-ratingcolor { color: '.self::get_setting(constants::SETTING_RATINGCOLOR).';}'."\n".

            '.tool_courserating-norating .tool_courserating-stars { color: '.constants::COLOR_GRAY.';}'."\n".

            '.tool_courserating-barcolor { background-color: '.self::get_setting(constants::SETTING_STARCOLOR).';}'."\n";

    }

    /**

     * Finds a field by its shortname

     *

     * @param string $shortname

     * @return field_controller|null

     */

    protected static function find_custom_field_by_shortname(string $shortname): ?field_controller {

        $handler = \core_course\customfield\course_handler::create();

        $categories = $handler->get_categories_with_fields();

        foreach ($categories as $category) {

            foreach ($category->get_fields() as $field) {

                if ($field->get('shortname') === $shortname) {

                    return $field;

                }

            }

        }

        return null;

    }

    /**

     * Create a custom course field if it does not exist

     *

     * @param string $shortname

     * @param string $type i.e. 'textarea', 'select', 'text

     * @param null|\lang_string $displayname

     * @param array $config additional field configuration, for example, options for 'select' element

     * @param string $description

     * @return field_controller|null

     */

    protected static function create_custom_field(string $shortname, string $type = 'text', ?\lang_string $displayname = null,

                                               array $config = [], string $description = ''): ?field_controller {

        $handler = \core_course\customfield\course_handler::create();

        $categories = $handler->get_categories_with_fields();

        if (empty($categories)) {

            $categoryid = $handler->create_category();

            $category = \core_customfield\category_controller::create($categoryid);

        } else {

            $category = reset($categories);

        }

        $config += [

            'defaultvalue' => '',

            'defaultvalueformat' => 1,

            'visibility' => \core_course\customfield\course_handler::VISIBLETOALL,

            'required' => 0,

            'uniquevalues' => 0,

            'locked' => 0,

        ];

        $record = (object)[

            'type' => $type,

            'shortname' => $shortname,

            'name' => $displayname ? (string)$displayname : $shortname,

            'descriptionformat' => FORMAT_HTML,

            'description' => $description,

            'configdata' => json_encode($config),

        ];

        try {

            $field = \core_customfield\field_controller::create(0, $record, $category);

        } catch (\moodle_exception $e) {

            return null;

        }

        $handler->save_field_configuration($field, $record);

        // Fetch the field again because the categories cache was rebuilt.

        return self::find_custom_field_by_shortname($shortname);

    }

    /**

     * Retrieve course custom field responsible for storing course ratings, create if not found

     *

     * @return field_controller|null

     */

    public static function get_course_rating_field(): ?field_controller {

        $shortname = constants::CFIELD_RATING;

        $field = self::find_custom_field_by_shortname($shortname);

        if (!self::course_ratings_enabled_anywhere()) {

            if ($field) {

                $field->get_handler()->delete_field_configuration($field);

            }

            return null;

        }

        return $field ?? self::create_custom_field($shortname,

            'textarea',

            new \lang_string('ratinglabel', 'tool_courserating'),

            ['locked' => 1],

            get_string('cfielddescription', 'tool_courserating'));

    }

    /**

     * Retrieve course custom field responsible for configuring per-course course rating mode, create if needed

     *

     * @return field_controller|null

     */

    public static function get_course_rating_mode_field(): ?field_controller {

        $shortname = constants::CFIELD_RATINGMODE;

        $field = self::find_custom_field_by_shortname($shortname);

        if (!self::get_setting(constants::SETTING_PERCOURSE)) {

            if ($field) {

                $field->get_handler()->delete_field_configuration($field);

            }

            return null;

        }

        $options = constants::rated_courses_options();

        $description = get_string('ratebydefault', 'tool_courserating',

            $options[self::get_setting(constants::SETTING_RATINGMODE)]);

        $field = $field ?? self::create_custom_field($shortname,

            'select',

            new \lang_string('ratingmode', 'tool_courserating'),

            [

                'visibility' => \core_course\customfield\course_handler::NOTVISIBLE,

                'options' => join("\n", $options),

            ],

            $description);

        if ($field && $field->get('description') !== $description) {

            $field->set('description', $description);

            $field->save();

        }

        return $field;

    }

    /**

     * Delete all course custom fields created by this plugin (on uninstall)

     *

     * @return void

     */

    public static function delete_all_custom_fields() {

        $shortname = constants::CFIELD_RATINGMODE;

        if ($field = self::find_custom_field_by_shortname($shortname)) {

            $field->get_handler()->delete_field_configuration($field);

        }

        $shortname = constants::CFIELD_RATING;

        if ($field = self::find_custom_field_by_shortname($shortname)) {

            $field->get_handler()->delete_field_configuration($field);

        }

    }

    /**

     * Retireve data stored in a course custom field

     *

     * @param int $courseid

     * @param string $shortname

     * @return data_controller|null

     */

    protected static function get_custom_field_data(int $courseid, string $shortname): ?data_controller {

        if ($f = self::find_custom_field_by_shortname($shortname)) {

            $fields = \core_customfield\api::get_instance_fields_data([$f->get('id') => $f], $courseid);

            foreach ($fields as $data) {

                if (!$data->get('id')) {

                    $data->set('contextid', \context_course::instance($courseid)->id);

                }

                return $data;

            }

        }

        return null;

    }

    /**

     * Retrieve data stored in a course rating course custom field

     *

     * @param int $courseid

     * @return data_controller|null

     */

    public static function get_course_rating_data_in_cfield(int $courseid): ?data_controller {

        return self::get_custom_field_data($courseid, constants::CFIELD_RATING);

    }

    /**

     * Retireve data stored in a rating mode custom course field

     *

     * @param int $courseid

     * @return data_controller|null

     */

    public static function get_course_rating_enabled_data_in_cfield(int $courseid): ?data_controller {

        return self::get_custom_field_data($courseid, constants::CFIELD_RATINGMODE);

    }

    /**

     * Calculate the rating mode for a specific course

     *

     * @param int $courseid

     * @return int

     */

    public static function get_course_rating_mode(int $courseid): int {

        $mode = self::get_setting(constants::SETTING_RATINGMODE);

        if (self::get_setting(constants::SETTING_PERCOURSE)) {

            if ($data = self::get_course_rating_enabled_data_in_cfield($courseid)) {

                $modecourse = (int)$data->get('intvalue');

                if (array_key_exists($modecourse, constants::rated_courses_options())) {

                    // Value is overridden for this course.

                    return $modecourse;

                }

            }

        }

        return $mode;

    }

    /**

     * Formatter for average rating

     *

     * @param float|null $avgrating

     * @param string $default

     * @return string

     */

    public static function format_avgrating(?float $avgrating, string $default = ''): string {

        return $avgrating ? sprintf("%.1f", $avgrating) : $default;

    }

    /**

     * Formatter for stars

     *

     * @param float|null $avgrating

     * @param \renderer_base|null $output

     * @return string

     */

    public static function stars(?float $avgrating, ?\renderer_base $output = null): string {

        global $PAGE;

        if (!$avgrating) {

            return '';

        }

        $output = $output ?? $PAGE->get_renderer('tool_courserating');

        return $output->render_from_template('tool_courserating/stars',

            (new stars_exporter($avgrating))->export($output));

    }

    /**

     * Formatter for date

     * @param int $value

     * @return string

     */

    public static function format_date($value): string {

        return $value ? userdate($value, get_string('strftimedatetimeshort', 'core_langconfig')) : '';

    }

    /**

     * Formatter for review

     *

     * @param string $value

     * @param \stdClass $row

     * @return string

     */

    public static function format_review($value, \stdClass $row): string {

        if (empty($row->id) || !strlen($row->review ?? '')) {

            return '';

        }

        $context = !empty($row->courseid) ? \context_course::instance($row->courseid) : \context_system::instance();

        $formatparams = [

            'options' => [],

            'striplinks' => true,

            'component' => 'tool_courserating',

            'filearea' => 'review',

            'itemid' => $row->id,

            'context' => $context,

        ];

        if (self::get_setting(constants::SETTING_USEHTML)) {

            list($text, $format) = external_format_text($row->review, FORMAT_HTML, $formatparams['context'],

                $formatparams['component'], $formatparams['filearea'], $formatparams['itemid'], $formatparams['options']);

            return $text;

        } else {

            return format_text(clean_param($row->review, PARAM_TEXT), FORMAT_MOODLE, ['context' => $context]);

        }

    }

    /**

     * Actions column

     *

     * @param int $id

     * @param \stdClass $row

     * @return string

     */

    public static function format_actions($id, $row): string {

        if (!$id || !permission::can_delete_rating($id, $row->courseid)) {

            return '';

        }

        return "<span data-for=\"tool_courserating-rbcell\" data-ratingid=\"$id\">".

            "<a href=\"#\" data-action=\"tool_courserating-delete-rating\" data-ratingid=\"$id\">".

            get_string('deleterating', 'tool_courserating')."</a></span>";

    }

    /**

     * Format individual student rating in the course report

     *

     * @param int $rating

     * @param \stdClass $row

     * @return string

     */

    public static function format_rating_in_course_report($rating, $row): string {

        if (!$rating) {

            return '';

        }

        return \html_writer::span(

            self::stars((float)$rating).

            \html_writer::span($rating, 'tool_courserating-ratingcolor ml-2'),

            'tool_courserating-reportrating');

    }

    /**

     * Format flags count in course report

     *

     * @param int|null $nofflags

     * @param \stdClass $row

     * @return string

     */

    public static function format_flags_in_course_report(?int $nofflags, \stdClass $row): string {

        return $nofflags ? "<span class=\"badge badge-warning\">$nofflags</span>" : '';

    }

}