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 core_completion\form;

use core_grades\component_gradeitems;

use cm_info;

/**

 * Completion trait helper, with methods to add completion elements and validate them.

 *

 * @package    core_completion

 * @since      Moodle 4.3

 * @copyright  2023 Sara Arjona (sara@moodle.com)

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

 */

trait form_trait {

    /** @var string The suffix to be added to the completion elements when creating them (for example, 'completion_assign'). */

    protected $suffix = '';

    /**

     * Called during validation.

     * Override this method to indicate, based on the data, whether a custom completion rule is selected or not.

     *

     * @param array $data Input data (not yet validated)

     * @return bool True if one or more rules are enabled; false if none are.

     */

    abstract protected function completion_rule_enabled($data);

    /**

     * Add completion elements to the form and return the list of element ids.

     *

     * @return array Array of string IDs of added items, empty array if none

     */

    abstract protected function add_completion_rules();

    /**

     * Get the form associated to this class, where the completion elements will be added.

     * This method must be overriden by the class using this trait if it doesn't include a _form property.

     *

     * @return \MoodleQuickForm

     * @throws \coding_exception If the class does not have a _form property.

     */

    protected function get_form(): \MoodleQuickForm {

        if (property_exists($this, '_form')) {

            return $this->_form;

        }

        throw new \coding_exception('This class does not have a _form property. Please, add it or override the get_form() method.');

    }

    /**

     * Set the suffix to be added to the completion elements when creating them (for example, 'completion_assign').

     *

     * @param string $suffix

     */

    public function set_suffix(string $suffix): void {

        $this->suffix = $suffix;

    }

    /**

     * Get the suffix to be added to the completion elements when creating them (for example, 'completion_assign').

     *

     * @return string The suffix

     */

    public function get_suffix(): string {

        return $this->suffix;

    }

    /**

     * Add completion elements to the form.

     *

     * @param string|null $modname The module name (for example, 'assign'). If null and form is moodleform_mod, the parameters are

     *                             overriden with the expected values from the form.

     * @param bool $supportviews True if the module supports views and false otherwise.

     * @param bool $supportgrades True if the module supports grades and false otherwise.

     * @param bool $rating True if the rating feature is enabled and false otherwise.

     * @param int|null $courseid Course where to add completion elements.

     * @throws \coding_exception If the form is not moodleform_mod and $modname is null.

     */

    protected function add_completion_elements(

        string $modname = null,

        bool $supportviews = false,

        bool $supportgrades = false,

        bool $rating = false,

        ?int $courseid = null

    ): void {

        global $SITE;

        $mform = $this->get_form();

        if ($modname === null) {

            if ($this instanceof \moodleform_mod) {

                // By default, all the modules can be initiatized with the same parameters.

                $modname = $this->_modname;

                $supportviews = plugin_supports('mod', $modname, FEATURE_COMPLETION_TRACKS_VIEWS, false);

                $supportgrades = plugin_supports('mod', $modname, FEATURE_GRADE_HAS_GRADE, false);

                $rating = $this->_features->rating;

            } else {

                throw new \coding_exception('You must specify the modname parameter if you are not using a moodleform_mod.');

            }

        }

        // Unlock button if people have completed it. The button will be removed later in definition_after_data if they haven't.

        // The unlock buttons don't need suffix because they are only displayed in the module settings page.

        $mform->addElement('submit', 'unlockcompletion', get_string('unlockcompletion', 'completion'));

        $mform->registerNoSubmitButton('unlockcompletion');

        $mform->addElement('hidden', 'completionunlocked', 0);

        $mform->setType('completionunlocked', PARAM_INT);

        $trackingdefault = COMPLETION_TRACKING_NONE;

        // Get the sufix to add to the completion elements name.

        $suffix = $this->get_suffix();

        $completionel = 'completion' . $suffix;

        $mform->addElement(

            'radio',

            $completionel,

            '',

            get_string('completion_none', 'completion'),

            COMPLETION_TRACKING_NONE,

            ['class' => 'left-indented']

        );

        $mform->addElement(

            'radio',

            $completionel,

            '',

            get_string('completion_manual', 'completion'),

            COMPLETION_TRACKING_MANUAL,

            ['class' => 'left-indented']

        );

        $allconditionsel = 'allconditions' . $suffix;

        $allconditions = $mform->createElement(

            'static',

            $allconditionsel,

            '',

            get_string('allconditions', 'completion'));

        $conditionsgroupel = 'conditionsgroup' . $suffix;

        $mform->addGroup([$allconditions], $conditionsgroupel, '', null, false);

        $mform->hideIf($conditionsgroupel, $completionel, 'ne', COMPLETION_TRACKING_AUTOMATIC);

        $mform->setType($completionel, PARAM_INT);

        $mform->setDefault($completionel, COMPLETION_TRACKING_NONE);

        // Automatic completion once you view it.

        if ($supportviews) {

            $completionviewel = 'completionview' . $suffix;

            $mform->addElement(

                'checkbox',

                $completionviewel,

                '',

                get_string('completionview_desc', 'completion')

            );

            $mform->hideIf($completionviewel, $completionel, 'ne', COMPLETION_TRACKING_AUTOMATIC);

            // Check by default if automatic completion tracking is set.

            if ($trackingdefault == COMPLETION_TRACKING_AUTOMATIC) {

                $mform->setDefault($completionviewel, 1);

            }

        }

        // Automatic completion according to module-specific rules.

        $customcompletionelements = $this->add_completion_rules();

        if (property_exists($this, '_customcompletionelements')) {

            $this->_customcompletionelements = $customcompletionelements;

        }

        if ($customcompletionelements !== null) {

            foreach ($customcompletionelements as $element) {

                $mform->hideIf($element, $completionel, 'ne', COMPLETION_TRACKING_AUTOMATIC);

            }

        }

        // If the activity supports grading, the grade elements must be added.

        if ($supportgrades) {

            $this->add_completiongrade_elements($modname, $rating);

        }

        $autocompletionpossible = $supportviews || $supportgrades || (count($customcompletionelements) > 0);

        // Automatic option only appears if possible.

        if ($autocompletionpossible) {

            $automatic = $mform->createElement(

                'radio',

                $completionel,

                '',

                get_string('completion_automatic', 'completion'),

                COMPLETION_TRACKING_AUTOMATIC,

                ['class' => 'left-indented']

            );

            $mform->insertElementBefore($automatic, $conditionsgroupel);

        }

        // Completion expected at particular date? (For progress tracking).

        // We don't show completion expected at site level default completion.

        if ($courseid != $SITE->id) {

            $completionexpectedel = 'completionexpected' . $suffix;

            $mform->addElement('date_time_selector', $completionexpectedel, get_string('completionexpected', 'completion'),

                ['optional' => true]);

            $a = get_string('pluginname', $modname);

            $mform->addHelpButton($completionexpectedel, 'completionexpected', 'completion', '', false, $a);

            $mform->hideIf($completionexpectedel, $completionel, 'eq', COMPLETION_TRACKING_NONE);

        }

    }

    /**

     * Add completion grade elements to the form.

     *

     * @param string $modname The name of the module (for example, 'assign').

     * @param bool $rating True if the rating feature is enabled and false otherwise.

     */

    protected function add_completiongrade_elements(

        string $modname,

        bool $rating = false

    ): void {

        $mform = $this->get_form();

        // Get the sufix to add to the completion elements name.

        $suffix = $this->get_suffix();

        $completionel = 'completion' . $suffix;

        $completionelementexists = $mform->elementExists($completionel);

        $component = "mod_{$modname}";

        $itemnames = component_gradeitems::get_itemname_mapping_for_component($component);

        $indentation = ['parentclass' => 'ml-2'];

        $receiveagradeel = 'receiveagrade' . $suffix;

        $completionusegradeel = 'completionusegrade' . $suffix;

        $completionpassgradeel = 'completionpassgrade' . $suffix;

        if (count($itemnames) === 1) {

            // Only one gradeitem in this activity.

            // We use the completionusegrade field here.

            $mform->addElement(

                'checkbox',

                $completionusegradeel,

                '',

                get_string('completionusegrade_desc', 'completion')

            );

            // Complete if the user has reached any grade.

            $mform->addElement(

                'radio',

                $completionpassgradeel,

                null,

                get_string('completionanygrade_desc', 'completion'),

                0,

                $indentation

            );

            // Complete if the user has reached the pass grade.

            $mform->addElement(

                'radio',

                $completionpassgradeel,

                null,

                get_string('completionpassgrade_desc', 'completion'),

                1,

                $indentation

            );

            $mform->hideIf($completionpassgradeel, $completionusegradeel, 'notchecked');

            if ($completionelementexists) {

                $mform->hideIf($completionpassgradeel, $completionel, 'ne', COMPLETION_TRACKING_AUTOMATIC);

                $mform->hideIf($completionusegradeel, $completionel, 'ne', COMPLETION_TRACKING_AUTOMATIC);

            }

            // The disabledIf logic differs between ratings and other grade items due to different field types.

            if ($rating) {

                // If using the rating system, there is no grade unless ratings are enabled.

                $mform->hideIf($completionusegradeel, 'assessed', 'eq', 0);

                $mform->hideIf($completionusegradeel, 'assessed', 'eq', 0);

            } else {

                // All other field types use the '$gradefieldname' field's modgrade_type.

                $itemnumbers = array_keys($itemnames);

                $itemnumber = array_shift($itemnumbers);

                $gradefieldname = component_gradeitems::get_field_name_for_itemnumber($component, $itemnumber, 'grade');

                $mform->hideIf($completionusegradeel, "{$gradefieldname}[modgrade_type]", 'eq', 'none');

                $mform->hideIf($completionusegradeel, "{$gradefieldname}[modgrade_type]", 'eq', 'none');

            }

        } else if (count($itemnames) > 1) {

            // There are multiple grade items in this activity.

            // Show them all.

            $options = [];

            foreach ($itemnames as $itemnumber => $itemname) {

                $options[$itemnumber] = get_string("grade_{$itemname}_name", $component);

            }

            $group = [$mform->createElement(

                'checkbox',

                $completionusegradeel,

                null,

                get_string('completionusegrade_desc', 'completion')

            )];

            $completiongradeitemnumberel = 'completiongradeitemnumber' . $suffix;

            $group[] =& $mform->createElement(

                'select',

                $completiongradeitemnumberel,

                '',

                $options

            );

            $receiveagradegroupel = 'receiveagradegroup' . $suffix;

            $mform->addGroup($group, $receiveagradegroupel, '', [' '], false);

            if ($completionelementexists) {

                $mform->hideIf($completionusegradeel, $completionel, 'ne', COMPLETION_TRACKING_AUTOMATIC);

                $mform->hideIf($receiveagradegroupel, $completionel, 'ne', COMPLETION_TRACKING_AUTOMATIC);

            }

            $mform->hideIf($completiongradeitemnumberel, $completionusegradeel, 'notchecked');

            // Complete if the user has reached any grade.

            $mform->addElement(

                'radio',

                $completionpassgradeel,

                null,

                get_string('completionanygrade_desc', 'completion'),

                0,

                $indentation

            );

            // Complete if the user has reached the pass grade.

            $mform->addElement(

                'radio',

                $completionpassgradeel,

                null,

                get_string('completionpassgrade_desc', 'completion'),

                1,

                $indentation

            );

            $mform->hideIf($completionpassgradeel, $completionusegradeel, 'notchecked');

            if ($completionelementexists) {

                $mform->hideIf($completiongradeitemnumberel, $completionel, 'ne', COMPLETION_TRACKING_AUTOMATIC);

                $mform->hideIf($completionpassgradeel, $completionel, 'ne', COMPLETION_TRACKING_AUTOMATIC);

            }

        }

        $customgradingelements = $this->add_completiongrade_rules();

        if (property_exists($this, '_customcompletionelements')) {

            $this->_customcompletionelements = array_merge($this->_customcompletionelements, $customgradingelements);

        }

        if ($completionelementexists) {

            foreach ($customgradingelements as $customgradingelement) {

                $mform->hideIf($customgradingelement, $completionel, 'ne', COMPLETION_TRACKING_AUTOMATIC);

            }

        }

    }

    /**

     * Add completion grading elements to the form and return the list of element ids.

     *

     * @return array Array of string IDs of added items, empty array if none

     */

    abstract public function add_completiongrade_rules(): array;

    /**

     * Perform some extra validation for completion settings.

     *

     * @param array $data Array of ["fieldname" => value] of submitted data.

     * @return array List of ["element_name" => "error_description"] if there are errors or an empty array if everything is OK.

     */

    protected function validate_completion(array $data): array {

        $errors = [];

        // Get the sufix to add to the completion elements name.

        $suffix = $this->get_suffix();

        $completionel = 'completion' . $suffix;

        // Completion: Don't let them choose automatic completion without turning on some conditions.

        $automaticcompletion = array_key_exists($completionel, $data) && $data[$completionel] == COMPLETION_TRACKING_AUTOMATIC;

        // Ignore this check when completion settings are locked, as the options are then disabled.

        // The unlock buttons don't need suffix because they are only displayed in the module settings page.

        $automaticcompletion = $automaticcompletion && !empty($data['completionunlocked']);

        if ($automaticcompletion) {

            // View to complete.

            $completionviewel = 'completionview' . $suffix;

            $rulesenabled = !empty($data[$completionviewel]);

            // Use grade to complete (only one grade item).

            $completionusegradeel = 'completionusegrade' . $suffix;

            $completionpassgradeel = 'completionpassgrade' . $suffix;

            $rulesenabled = $rulesenabled || !empty($data[$completionusegradeel]) || !empty($data[$completionpassgradeel]);

            // Use grade to complete (specific grade item).

            $completiongradeitemnumberel = 'completiongradeitemnumber' . $suffix;

            if (!$rulesenabled && isset($data[$completiongradeitemnumberel])) {

                $rulesenabled = $data[$completiongradeitemnumberel] != '';

            }

            // Module-specific completion rules.

            $rulesenabled = $rulesenabled || $this->completion_rule_enabled($data);

            if (!$rulesenabled) {

                // No rules are enabled. Can't set automatically completed without rules.

                $errors[$completionel] = get_string('badautocompletion', 'completion');

            }

        }

        return $errors;

    }

    /**

     * It should be called from the definition_after_data() to setup the completion settings in the form.

     *

     * @param cm_info|null $cm The course module associated to this form.

     */

    protected function definition_after_data_completion(?cm_info $cm = null): void {

        global $COURSE, $SITE;

        $mform = $this->get_form();

        $completion = new \completion_info($COURSE);

        // We use $SITE course for site default activity completion,

        // so users could set default values regardless of whether completion is enabled or not.".

        if ($completion->is_enabled() || $COURSE->id == $SITE->id) {

            $suffix = $this->get_suffix();

            // If anybody has completed the activity, these options will be 'locked'.

            // We use $SITE course for site default activity completion, so we don't need any unlock button.

            $completedcount = (empty($cm) || $COURSE->id == $SITE->id) ? 0 : $completion->count_user_data($cm);

            $freeze = false;

            if (!$completedcount) {

                // The unlock buttons don't need suffix because they are only displayed in the module settings page.

                if ($mform->elementExists('unlockcompletion')) {

                    $mform->removeElement('unlockcompletion');

                }

                // Automatically set to unlocked. Note: this is necessary in order to make it recalculate completion once

                // the option is changed, maybe someone has completed it now.

                if ($mform->elementExists('completionunlocked')) {

                    $mform->getElement('completionunlocked')->setValue(1);

                }

            } else {

                // Has the element been unlocked, either by the button being pressed in this request, or the field already

                // being set from a previous one?

                if ($mform->exportValue('unlockcompletion') || $mform->exportValue('completionunlocked')) {

                    // Yes, add in warning text and set the hidden variable.

                    $completedunlockedel = $mform->createElement(

                        'static',

                        'completedunlocked',

                        get_string('completedunlocked', 'completion'),

                        get_string('completedunlockedtext', 'completion')

                    );

                    $mform->insertElementBefore($completedunlockedel, 'unlockcompletion');

                    $mform->removeElement('unlockcompletion');

                    $mform->getElement('completionunlocked')->setValue(1);

                } else {

                    // No, add in the warning text with the count (now we know it) before the unlock button.

                    $completedwarningel = $mform->createElement(

                        'static',

                        'completedwarning',

                        get_string('completedwarning', 'completion'),

                        get_string('completedwarningtext', 'completion', $completedcount)

                    );

                    $mform->insertElementBefore($completedwarningel, 'unlockcompletion');

                    $freeze = true;

                }

            }

            if ($freeze) {

                $completionel = 'completion' . $suffix;

                $mform->freeze($completionel);

                $completionviewel = 'completionview' . $suffix;

                if ($mform->elementExists($completionviewel)) {

                    // Don't use hardFreeze or checkbox value gets lost.

                    $mform->freeze($completionviewel);

                }

                $completionusegradeel = 'completionusegrade' . $suffix;

                if ($mform->elementExists($completionusegradeel)) {

                    $mform->freeze($completionusegradeel);

                }

                $completionpassgradeel = 'completionpassgrade' . $suffix;

                if ($mform->elementExists($completionpassgradeel)) {

                    $mform->freeze($completionpassgradeel);

                    // Has the completion pass grade completion criteria been set? If it has, then we shouldn't change

                    // the gradepass field.

                    if ($mform->exportValue($completionpassgradeel)) {

                        $mform->freeze('gradepass');

                    }

                }

                $completiongradeitemnumberel = 'completiongradeitemnumber' . $suffix;

                if ($mform->elementExists($completiongradeitemnumberel)) {

                    $mform->freeze($completiongradeitemnumberel);

                }

                if (property_exists($this, '_customcompletionelements')) {

                    $mform->freeze($this->_customcompletionelements);

                }

            }

        }

    }

}