lib.php

<?php

/**
 * Library of interface functions and constants.
 *
 * @copyright   2019 Université Grenoble Alpes
 * @license     http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
use mod_labnbook\fetch;

\defined('MOODLE_INTERNAL') || die();

\define('LABNBOOK_TABLE', 'labnbook');

/* @var $DB moodle_database */

/**
 * Return if the plugin supports $feature.
 *
 * @param string $feature constant representing the feature
 * @return true | null True if the feature is supported, null otherwise
 */
function labnbook_supports($feature)
{
    $features = [
        //FEATURE_BACKUP_MOODLE2,
        //FEATURE_GRADE_HAS_GRADE,
        //FEATURE_GRADE_OUTCOMES,
        FEATURE_GROUPS,
        FEATURE_MOD_INTRO,
        FEATURE_SHOW_DESCRIPTION,
    ];
    return \in_array($feature, $features) ? true : null;
}

/**
 * Saves a new instance of the mod_labnbook into the database.
 *
 * Given an object containing all the necessary data, (defined by the form
 * in mod_form.php) this function will create a new instance and return the id
 * number of the instance.
 *
 * @param object $moduleinstance an object from the form
 * @param mod_labnbook_mod_form $mform the form
 * @return int the id of the newly inserted record
 */
function labnbook_add_instance($moduleinstance, $mform = null)
{
    global $DB;

    $fetcher = new fetch\user();
    $groupid = (int) $moduleinstance->groupmode === 0 ? null : (int) $moduleinstance->group;
    $teamconfig = [
        'method' => $moduleinstance->method,
        'teams_max' => $moduleinstance->teams_max,
        'size_opt' => $moduleinstance->size_opt,
        'size_max' => $moduleinstance->size_max,
        'size_min' => $moduleinstance->size_min,
        'start_datetime' => isset($moduleinstance->startdate) ? \date('Y-m-d H:i:s', $moduleinstance->startdate) : null,
        'end_datetime' => isset($moduleinstance->enddate) ? \date('Y-m-d H:i:s', $moduleinstance->enddate) : null,
    ];
    try {
        $teamConfig = $fetcher->useMission(
            (int) $moduleinstance->labnbook_missionid,
            (int) $moduleinstance->course,
            $mform->get_course()->shortname,
            $groupid,
            $teamconfig
        );
    } catch (\Exception $e) {
        $error = $fetcher->getLastError();
        if ($error->code == 409) {
            print_error(get_string('error_duplicate_teaming', 'labnbook'));
        } else {
            die("fatal error: " . $error->message);
        }
    }
    if ($teamConfig->id_team_config) {
        $moduleinstance->labnbook_teamconfigid = (int) $teamConfig->id_team_config;
    } else {
        throw new moodle_exception("LabnBook return an invalid response.");
    }

    $moduleinstance->timecreated = \time();
    $id = $DB->insert_record(LABNBOOK_TABLE, $moduleinstance);

    return $id;
}

/**
 * Updates an instance of the mod_labnbook in the database.
 *
 * Given an object containing all the necessary data (defined in mod_form.php),
 * this function will update an existing instance with new data.
 *
 * @param object $moduleinstance An object from the form in mod_form.php.
 * @param mod_labnbook_mod_form $mform the form
 * @return bool true if successful, false otherwise
 */
function labnbook_update_instance($moduleinstance, $mform = null)
{
    global $DB;

    $moduleinstance->timemodified = \time();
    $moduleinstance->id = $moduleinstance->instance;

    $fetcher = new fetch\user();
    $groupid = (int) $moduleinstance->groupmode === 0 ? null : (int) $moduleinstance->group;
    $teamconfig = [
        'id_team_config' => $moduleinstance->labnbook_teamconfigid,
        'method' => $moduleinstance->method,
        'teams_max' => $moduleinstance->teams_max,
        'size_opt' => $moduleinstance->size_opt,
        'size_max' => $moduleinstance->size_max,
        'size_min' => $moduleinstance->size_min,
        'start_datetime' => isset($moduleinstance->startdate) ? \date('Y-m-d H:i:s', $moduleinstance->startdate) : null,
        'end_datetime' => isset($moduleinstance->enddate) ? \date('Y-m-d H:i:s', $moduleinstance->enddate) : null,
    ];
    try {
        $fetcher->updateMissionUse(
            (int) $moduleinstance->labnbook_missionid,
            (int) $moduleinstance->course,
            $mform->get_course()->shortname,
            $groupid,
            $teamconfig
        );
    } catch (\Exception $e) {
        die("fatal error: " . $e->getMessage()); // TODO
    }

    return $DB->update_record(LABNBOOK_TABLE, $moduleinstance);
}

/**
 * Removes an instance of the mod_labnbook from the database.
 *
 * @param int $id id of the module instance
 * @return bool true if successful, false on failure
 */
function labnbook_delete_instance($id)
{
    global $DB;

    $record = $DB->get_record(LABNBOOK_TABLE, ['id' => $id]);
    if (!$record) {
        return true;
    }
    try {
        $fetcher = new fetch\institution();
        $fetcher->deleteTeamconfig($record->labnbook_teamconfigid);
    } catch(\Exception $e) {
        $error = $fetcher->getLastError();
        // 404 means already removed in this case, we just ignore the error
        if ($error->code != 404) {
            throw $e;
        }
    }
    $DB->delete_records(LABNBOOK_TABLE, ['id' => $id]);
}

/**
 * Given a course_module object, this function returns any
 * "extra" information that may be needed when printing
 * this activity in a course listing.
 *
 * See {@link get_array_of_activities()} in course/lib.php
 *
 * @param stdClass $coursemodule
 * @return cached_cm_info Info to customise main page display
 */
function labnbook_get_coursemodule_info($coursemodule)
{
    global $CFG, $DB;
    require_once("$CFG->libdir/resourcelib.php");

    $instance = $DB->get_record(
        LABNBOOK_TABLE,
        ['id' => $coursemodule->instance],
        'id, name, intro, introformat'
    );
    if (!$instance) {
        return null;
    }

    $info = new cached_cm_info();
    $info->name = $instance->name;
    if ($coursemodule->showdescription) {
        // Convert intro to html. Do not filter cached version, filters run at display time.
        $info->content = format_module_intro('labnbook', $instance, $coursemodule->id, false);
    }
    /*
    // Configured to open the activity in a new tab
    if ($instance->display === RESOURCELIB_DISPLAY_POPUP) {
        // ...
        $info->target = '_blank';
    }
     */

    return $info;
}

/**
 * Is a given scale used by the instance of mod_labnbook?
 *
 * This function returns if a scale is being used by one mod_labnbook
 * if it has support for grading and scales.
 *
 * @param int $moduleinstanceid ID of an instance of this module
 * @param int $scaleid ID of the scale
 * @return bool true if the scale is used by the given mod_labnbook instance
 */
function labnbook_scale_used($moduleinstanceid, $scaleid)
{
    global $DB;

    if ($scaleid && $DB->record_exists(LABNBOOK_TABLE, ['id' => $moduleinstanceid, 'grade' => -$scaleid])) {
        return true;
    }
    return false;
}

/**
 * Checks if scale is being used by any instance of mod_labnbook.
 *
 * This is used to find out if scale used anywhere.
 *
 * @param int $scaleid ID of the scale
 * @return bool true if the scale is used by any mod_labnbook instance
 */
function labnbook_scale_used_anywhere($scaleid)
{
    global $DB;

    if ($scaleid and $DB->record_exists(LABNBOOK_TABLE, ['grade' => -$scaleid])) {
        return true;
    }
    return false;
}

/**
 * Creates or updates grade item for the given mod_labnbook instance.
 *
 * Needed by {@link grade_update_mod_grades()}.
 *
 * @param stdClass $moduleinstance instance object with extra cmidnumber and modname property
 * @param bool $reset reset grades in the gradebook
 * @return void
 */
function labnbook_grade_item_update($moduleinstance, $reset=false)
{
    global $CFG;
    require_once($CFG->libdir . '/gradelib.php');

    $item = [];
    $item['itemname'] = clean_param($moduleinstance->name, PARAM_NOTAGS);
    $item['gradetype'] = GRADE_TYPE_VALUE;

    if ($moduleinstance->grade > 0) {
        $item['gradetype'] = GRADE_TYPE_VALUE;
        $item['grademax']  = $moduleinstance->grade;
        $item['grademin']  = 0;
    } elseif ($moduleinstance->grade < 0) {
        $item['gradetype'] = GRADE_TYPE_SCALE;
        $item['scaleid']   = -$moduleinstance->grade;
    } else {
        $item['gradetype'] = GRADE_TYPE_NONE;
    }
    if ($reset) {
        $item['reset'] = true;
    }

    grade_update('/mod/labnbook', $moduleinstance->course, 'mod', LABNBOOK_TABLE, $moduleinstance->id, 0, null, $item);
}

/**
 * Delete grade item for given mod_labnbook instance.
 *
 * @param stdClass $moduleinstance instance object
 * @return grade_item
 */
function labnbook_grade_item_delete($moduleinstance)
{
    global $CFG;
    require_once($CFG->libdir . '/gradelib.php');

    return grade_update(
        '/mod/labnbook',
        $moduleinstance->course,
        'mod',
        LABNBOOK_TABLE,
        $moduleinstance->id,
        0,
        null,
        ['deleted' => 1]
    );
}

/**
 * Update mod_labnbook grades in the gradebook.
 *
 * Needed by {@link grade_update_mod_grades()}.
 *
 * @param stdClass $moduleinstance instance object with extra cmidnumber and modname property
 * @param int $userid update grade of specific user only, 0 means all participants
 */
function labnbook_update_grades($moduleinstance, $userid = 0)
{
    global $CFG;
    require_once($CFG->libdir . '/gradelib.php');

    // Populate array of grade objects indexed by userid.
    $grades = [];
    grade_update('/mod/labnbook', $moduleinstance->course, 'mod', LABNBOOK_TABLE, $moduleinstance->id, 0, $grades);
}

/**
 * Extends the global navigation tree by adding mod_labnbook nodes if there is a relevant content.
 *
 * This can be called by an AJAX request so do not rely on $PAGE as it might not be set up properly.
 *
 * @param navigation_node $labnbooknode an object representing the navigation tree node
 * @param stdClass $course
 * @param stdClass $module
 * @param cm_info $cm
 */
function labnbook_extend_navigation($labnbooknode, $course, $module, $cm)
{
}

/**
 * Extends the settings navigation with the mod_labnbook settings.
 *
 * This function is called when the context for the page is a mod_labnbook module.
 * This is not called by AJAX so it is safe to rely on the $PAGE.
 *
 * @param settings_navigation $settingsnav {@link settings_navigation}
 * @param navigation_node $labnbooknode {@link navigation_node}
 */
function labnbook_extend_settings_navigation($settingsnav, $labnbooknode = null)
{
}