Proyectos de Subversion Moodle

// 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/>.

/**

 * This module provides functionality for managing weight calculations and adjustments for grade items.

 *

 * @module     core_grades/edittree_weight

 * @copyright  2023 Shamim Rezaie <shamim@moodle.com>

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

 */

import {getString} from 'core/str';

import {prefetchStrings} from 'core/prefetch';

/**

 * Selectors.

 *

 * @type {Object}

 */

const selectors = {

    weightOverrideCheckbox: 'input[type="checkbox"][name^="weightoverride_"]',

    weightOverrideInput: 'input[type="text"][name^="weight_"]',

    aggregationForCategory: category => `[data-aggregationforcategory='${category}']`,

    childrenByCategory: category => `tr[data-parent-category="${category}"]`,

    categoryByIdentifier: identifier => `tr.category[data-category="${identifier}"]`,

};

/**

 * An object representing grading-related constants.

 * The same as what's defined in lib/grade/constants.php.

 *

 * @type {Object}

 * @property {Object} aggregation Aggregation settings.

 * @property {number} aggregation.sum Aggregation method: sum.

 * @property {Object} type Grade type settings.

 * @property {number} type.none Grade type: none.

 * @property {number} type.value Grade type: value.

 * @property {number} type.scale Grade type: scale.

 */

const grade = {

    aggregation: {

        sum: 13,

    },

};

/**

 * The character used as the decimal separator for number formatting.

 *

 * @type {string}

 */

let decimalSeparator;

/**

 * This setting indicates if we should use algorithm prior to MDL-49257 fix for calculating extra credit weights.

 * Even though the old algorithm has bugs in it, we need to preserve existing grades.

 *

 * @type {boolean}

 */

let oldExtraCreditCalculation;

/**

 * Recalculates the natural weights for grade items within a given category.

 *

 * @param {HTMLElement} categoryElement The DOM element representing the category.

 */

// Suppress 'complexity' linting rule to keep this function as close to grade_category::auto_update_weights.

// eslint-disable-next-line complexity

const recalculateNaturalWeights = (categoryElement) => {

    const childElements = document.querySelectorAll(selectors.childrenByCategory(categoryElement.dataset.category));

    // Calculate the sum of the grademax's of all the items within this category.

    let totalGradeMax = 0;

    // Out of 100, how much weight has been manually overridden by a user?

    let totalOverriddenWeight = 0;

    let totalOverriddenGradeMax = 0;

    // Has every assessment in this category been overridden?

    let automaticGradeItemsPresent = false;

    // Does the grade item require normalising?

    let requiresNormalising = false;

    // Is there an error in the weight calculations?

    let erroneous = false;

    // This array keeps track of the id and weight of every grade item that has been overridden.

    const overrideArray = {};

    for (const childElement of childElements) {

        const weightInput = childElement.querySelector(selectors.weightOverrideInput);

        const weightCheckbox = childElement.querySelector(selectors.weightOverrideCheckbox);

        // There are cases where a grade item should be excluded from calculations:

        // - If the item's grade type is 'text' or 'none'.

        // - If the grade item is an outcome item and the settings are set to not aggregate outcome items.

        // - If the item's grade type is 'scale' and the settings are set to ignore scales in aggregations.

        // All these cases are already taken care of in the backend, and no 'weight' input element is rendered on the page

        // if a grade item should not have a weight.

        if (!weightInput) {

            continue;

        }

        const itemWeight = parseWeight(weightInput.value);

        const itemAggregationCoefficient = parseInt(childElement.dataset.aggregationcoef);

        const itemGradeMax = parseFloat(childElement.dataset.grademax);

        // Record the ID and the weight for this grade item.

        overrideArray[childElement.dataset.itemid] = {

            extraCredit: itemAggregationCoefficient,

            weight: itemWeight,

            weightOverride: weightCheckbox.checked,

        };

        // If this item has had its weight overridden then set the flag to true, but

        // only if all previous items were also overridden. Note that extra credit items

        // are counted as overridden grade items.

        if (!weightCheckbox.checked && itemAggregationCoefficient === 0) {

            automaticGradeItemsPresent = true;

        }

        if (itemAggregationCoefficient > 0) {

            // An extra credit grade item doesn't contribute to totalOverriddenGradeMax.

            continue;

        } else if (weightCheckbox.checked && itemWeight <= 0) {

            // An overridden item that defines a weight of 0 does not contribute to totalOverriddenGradeMax.

            continue;

        }

        totalGradeMax += itemGradeMax;

        if (weightCheckbox.checked) {

            totalOverriddenWeight += itemWeight;

            totalOverriddenGradeMax += itemGradeMax;

        }

    }

    // Initialise this variable (used to keep track of the weight override total).

    let normaliseTotal = 0;

    // Keep a record of how much the override total is to see if it is above 100. If it is then we need to set the

    // other weights to zero and normalise the others.

    let overriddenTotal = 0;

    // Total up all the weights.

    for (const gradeItemDetail of Object.values(overrideArray)) {

        // Exclude grade items with extra credit or negative weights (which will be set to zero later).

        if (!gradeItemDetail.extraCredit && gradeItemDetail.weight > 0) {

            normaliseTotal += gradeItemDetail.weight;

        }

        // The overridden total includes items that are marked as overridden, not extra credit, and have a positive weight.

        if (gradeItemDetail.weightOverride && !gradeItemDetail.extraCredit && gradeItemDetail.weight > 0) {

            // Add overridden weights up to see if they are greater than 1.

            overriddenTotal += gradeItemDetail.weight;

        }

    }

    if (overriddenTotal > 100) {

        // Make sure that this category of weights gets normalised.

        requiresNormalising = true;

        // The normalised weights are only the overridden weights, so we just use the total of those.

        normaliseTotal = overriddenTotal;

    }

    const totalNonOverriddenGradeMax = totalGradeMax - totalOverriddenGradeMax;

    for (const childElement of childElements) {

        const weightInput = childElement.querySelector(selectors.weightOverrideInput);

        const weightCheckbox = childElement.querySelector(selectors.weightOverrideCheckbox);

        const itemAggregationCoefficient = parseInt(childElement.dataset.aggregationcoef);

        const itemGradeMax = parseFloat(childElement.dataset.grademax);

        if (!weightInput) {

            continue;

        } else if (!oldExtraCreditCalculation && itemAggregationCoefficient > 0 && weightCheckbox.checked) {

            // For an item with extra credit ignore other weights and overrides but do not change anything at all

            // if its weight was already overridden.

            continue;

        }

        // Remove any error messages and classes.

        weightInput.classList.remove('is-invalid');

        const errorArea = weightInput.closest('td').querySelector('.invalid-feedback');

        errorArea.textContent = '';

        if (!oldExtraCreditCalculation && itemAggregationCoefficient > 0 && !weightCheckbox.checked) {

            // For an item with extra credit ignore other weights and overrides.

            weightInput.value = totalGradeMax ? formatFloat(itemGradeMax * 100 / totalGradeMax) : 0;

        } else if (!weightCheckbox.checked) {

            // Calculations with a grade maximum of zero will cause problems. Just set the weight to zero.

            if (totalOverriddenWeight >= 100 || totalNonOverriddenGradeMax === 0 || itemGradeMax === 0) {

                // There is no more weight to distribute.

                weightInput.value = formatFloat(0);

            } else {

                // Calculate this item's weight as a percentage of the non-overridden total grade maxes

                // then convert it to a proportion of the available non-overridden weight.

                weightInput.value = formatFloat((itemGradeMax / totalNonOverriddenGradeMax) * (100 - totalOverriddenWeight));

            }

        } else if ((!automaticGradeItemsPresent && normaliseTotal !== 100) || requiresNormalising ||

                overrideArray[childElement.dataset.itemid].weight < 0) {

            if (overrideArray[childElement.dataset.itemid].weight < 0) {

                weightInput.value = formatFloat(0);

            }

            // Zero is a special case. If the total is zero then we need to set the weight of the parent category to zero.

            if (normaliseTotal !== 0) {

                erroneous = true;

                const error = normaliseTotal > 100 ? 'erroroverweight' : 'errorunderweight';

                // eslint-disable-next-line promise/always-return,promise/catch-or-return

                getString(error, 'core_grades').then((errorString) => {

                    errorArea.textContent = errorString;

                });

                weightInput.classList.add('is-invalid');

            }

        }

    }

    if (!erroneous) {

        const categoryGradeMax = parseFloat(categoryElement.dataset.grademax);

        if (categoryGradeMax !== totalGradeMax) {

            // The category grade max is not the same as the total grade max, so we need to update the category grade max.

            categoryElement.dataset.grademax = totalGradeMax;

            const relatedCategoryAggregationRow = document.querySelector(

                selectors.aggregationForCategory(categoryElement.dataset.category)

            );

            relatedCategoryAggregationRow.querySelector('.column-range').innerHTML = formatFloat(totalGradeMax, 2, 2);

            const parentCategory = document.querySelector(selectors.categoryByIdentifier(categoryElement.dataset.parentCategory));

            if (parentCategory && (parseInt(parentCategory.dataset.aggregation) === grade.aggregation.sum)) {

                recalculateNaturalWeights(parentCategory);

            }

        }

    }

};

/**

 * Formats a floating-point number as a string with the specified number of decimal places.

 * Unnecessary trailing zeros are removed up to the specified minimum number of decimal places.

 *

 * @param {number} number The float value to be formatted.

 * @param {number} [decimalPoints=3] The number of decimal places to use.

 * @param {number} [minDecimals=1] The minimum number of decimal places to use.

 * @returns {string} The formatted weight value with the specified decimal places.

 */

const formatFloat = (number, decimalPoints = 3, minDecimals = 1) => {

    return number.toFixed(decimalPoints)

        .replace(new RegExp(`0{0,${decimalPoints - minDecimals}}$`), '')

        .replace('.', decimalSeparator);

};

/**

 * Parses a weight string and returns a normalized float value.

 *

 * @param {string} weightString The weight as a string, possibly with localized formatting.

 * @returns {number} The parsed weight as a float. If parsing fails, returns 0.

 */

const parseWeight = (weightString) => {

    const normalizedWeightString = weightString.replace(decimalSeparator, '.');

    return isNaN(Number(normalizedWeightString)) ? 0 : parseFloat(normalizedWeightString || 0);

};

/**

 * Initializes the weight management module with optional configuration.

 *

 * @param {string} decSep The character used as the decimal separator for number formatting.

 * @param {boolean} oldCalculation A flag indicating whether to use the old (pre MDL-49257) extra credit calculation.

 */

export const init = (decSep, oldCalculation) => {

    decimalSeparator = decSep;

    oldExtraCreditCalculation = oldCalculation;

    prefetchStrings('core_grades', ['erroroverweight', 'errorunderweight']);

    document.addEventListener('change', e => {

        // Update the weights of all grade items in the category when the weight of any grade item in the category is changed.

        if (e.target.matches(selectors.weightOverrideInput) || e.target.matches(selectors.weightOverrideCheckbox)) {

            // The following is named gradeItemRow, but it may also be a row that's representing a grade category.

            // It's ok because it serves as the categories associated grade item in our calculations.

            const gradeItemRow = e.target.closest('tr');

            const categoryElement = document.querySelector(selectors.categoryByIdentifier(gradeItemRow.dataset.parentCategory));

            // This is only required if we are using natural weights.

            if (parseInt(categoryElement.dataset.aggregation) === grade.aggregation.sum) {

                const weightElement = gradeItemRow.querySelector(selectors.weightOverrideInput);

                weightElement.value = formatFloat(Math.max(0, parseWeight(weightElement.value)));

                recalculateNaturalWeights(categoryElement);

            }

        }

    });

    document.addEventListener('submit', e => {

        // If the form is being submitted, then we need to ensure that the weight input fields are all set to

        // a valid value.

        if (e.target.matches('#gradetreeform')) {

            const firstInvalidWeightInput = e.target.querySelector('input.is-invalid');

            if (firstInvalidWeightInput) {

                const firstFocusableInvalidWeightInput = e.target.querySelector('input.is-invalid:enabled');

                if (firstFocusableInvalidWeightInput) {

                    firstFocusableInvalidWeightInput.focus();

                } else {

                    firstInvalidWeightInput.scrollIntoView({block: 'center'});

                }

                e.preventDefault();

            }

        }

    });

};