moodle_local_treestudyplan/classes/studyplanservice.php

1782 lines
65 KiB
PHP
Raw Normal View History

<?php
2023-08-24 23:02:41 +02:00
// This file is part of the Studyplan plugin for Moodle
//
// 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 <https://www.gnu.org/licenses/>.
/**
2023-08-27 23:27:07 +02:00
* Webservice class for managing studyplans
2023-08-24 23:02:41 +02:00
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
namespace local_treestudyplan;
2023-08-25 12:04:27 +02:00
defined('MOODLE_INTERNAL') || die();
use local_treestudyplan\local\helpers\webservicehelper;
require_once($CFG->libdir.'/externallib.php');
require_once($CFG->libdir.'/badgeslib.php');
require_once($CFG->libdir.'/gradelib.php');
require_once($CFG->dirroot.'/course/modlib.php');
2023-08-27 23:27:07 +02:00
/**
* Webservice class for managing studyplans
*/
2023-08-25 10:41:56 +02:00
class studyplanservice extends \external_api {
2023-08-27 23:27:07 +02:00
/**
* Capability required to edit study plans
* @var string
*/
const CAP_EDIT = "local/treestudyplan:editstudyplan";
2023-08-27 23:27:07 +02:00
/**
* Capability required to view studyplans (for other users)
* @var string
*/
const CAP_VIEW = "local/treestudyplan:viewuserreports";
/************************
* *
* list_studyplans *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function list_studyplans
*/
2023-08-28 08:51:52 +02:00
public static function list_studyplans_parameters() : \external_function_parameters {
return new \external_function_parameters([
"context_id" => new \external_value(PARAM_INT, 'context to search in for studyplans', VALUE_DEFAULT),
]);
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function list_studyplans
*/
2023-08-28 11:26:14 +02:00
public static function list_studyplans_returns() : \external_description {
return new \external_multiple_structure( studyplan::simple_structure() );
}
2023-08-27 23:27:07 +02:00
/**
* Get overview of all studyplans in a given context
* @param int $contextid Id of context to view (defaults to systemcontext)
* @return array
*/
2023-08-25 09:33:42 +02:00
public static function list_studyplans($contextid = 0) {
global $CFG, $DB;
2023-08-24 23:02:41 +02:00
// Check if the user has the correct permissions for this context.
2023-08-25 09:33:42 +02:00
$context = webservicehelper::find_context($contextid);
2023-08-24 23:02:41 +02:00
webservicehelper::require_capabilities([self::CAP_EDIT, self::CAP_VIEW], $context);
2023-08-24 23:02:41 +02:00
// Now list all the studyplans in the relevant context.
$list = [];
2023-08-25 09:33:42 +02:00
$studyplans = studyplan::find_all($contextid);
2023-08-24 23:02:41 +02:00
foreach ($studyplans as $studyplan) {
$list[] = $studyplan->simple_model();
}
return $list;
}
/************************
* *
* get_studyplan_map *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function get_studyplan_map
*/
2023-08-28 08:51:52 +02:00
public static function get_studyplan_map_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"id" => new \external_value(PARAM_INT, 'id of a studyplan to check usage on', VALUE_REQUIRED),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function get_studyplan_map
*/
2023-08-28 11:26:14 +02:00
public static function get_studyplan_map_returns() : \external_description {
return studyplan::editor_structure();
}
2023-08-27 23:27:07 +02:00
/**
* Get editor model for specific studyplan
* @param int $id Id of studyplan
* @return array
*/
2023-08-24 23:02:41 +02:00
public static function get_studyplan_map($id) {
if (isset($id) && $id > 0) {
2023-08-25 17:33:20 +02:00
$studyplan = studyplan::find_by_id($id);
2023-08-24 23:02:41 +02:00
webservicehelper::require_capabilities([self::CAP_EDIT, self::CAP_VIEW], $studyplan->context());
return $studyplan->editor_model();
2023-08-24 23:09:20 +02:00
} else {
return null;
}
}
/************************
* *
* get_studyline_map *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function get_studyline_map
*/
2023-08-28 08:51:52 +02:00
public static function get_studyline_map_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"id" => new \external_value(PARAM_INT, 'id of a studyline to check usage on', VALUE_DEFAULT),
]);
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function get_studyline_map
*/
2023-08-28 11:26:14 +02:00
public static function get_studyline_map_returns() : \external_description {
return new \external_multiple_structure( studyline::editor_structure() );
}
2023-08-27 23:27:07 +02:00
/**
* Get editor model for specific study line
* @param int $id ID of study line
* @return array
*/
2023-08-24 23:02:41 +02:00
public static function get_studyline_map($id) {
2023-08-25 17:33:20 +02:00
$o = studyline::find_by_id($id);
2023-08-24 23:02:41 +02:00
webservicehelper::require_capabilities([self::CAP_EDIT, self::CAP_VIEW], $o->context());
return $o->editor_model();
}
/************************
* *
* add_studyplan *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function add_studyplan
*/
2023-08-28 08:51:52 +02:00
public static function add_studyplan_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"name" => new \external_value(PARAM_TEXT, 'name of studyplan'),
2023-08-25 10:41:56 +02:00
"shortname" => new \external_value(PARAM_TEXT, 'shortname of studyplan'),
"idnumber" => new \external_value(PARAM_TEXT, 'idnumber of studyplan'),
"description" => new \external_value(PARAM_TEXT, 'description of studyplan'),
2023-08-03 18:44:57 +02:00
"periods" => new \external_value(PARAM_INT, 'number of periods in studyplan'),
"startdate" => new \external_value(PARAM_TEXT, 'start date of studyplan'),
"enddate" => new \external_value(PARAM_TEXT, 'end date of studyplan'),
2023-08-24 23:02:41 +02:00
"aggregation" => new \external_value(PARAM_TEXT, 'selected aggregator', VALUE_DEFAULT),
"aggregation_config" => new \external_value(PARAM_TEXT, 'config string for aggregator', VALUE_DEFAULT),
"context_id" => new \external_value(PARAM_INT, 'context of the study plan', VALUE_DEFAULT),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function add_studyplan
*/
2023-08-28 11:26:14 +02:00
public static function add_studyplan_returns() : \external_description {
return studyplan::simple_structure();
}
2023-08-27 23:27:07 +02:00
/**
* Add a new studyplan in a given context
* @param mixed $name
* @param mixed $shortname
* @param mixed $idnumber
* @param mixed $description
* @param mixed $periods
* @param mixed $startdate
* @param mixed $enddate
* @param string $aggregation
* @param string $aggregationconfig
* @param int $contextid
* @return array
*/
2023-08-25 11:52:05 +02:00
public static function add_studyplan($name, $shortname, $idnumber, $description, $periods,
2023-08-25 13:04:19 +02:00
$startdate, $enddate, $aggregation = "bistate", $aggregationconfig = '', $contextid = 0) {
2023-08-24 23:02:41 +02:00
// Check if we have the proper rights for the requested context.
2023-08-25 09:33:42 +02:00
$context = webservicehelper::find_context($contextid);
2023-08-24 23:02:41 +02:00
webservicehelper::require_capabilities(self::CAP_EDIT, $context);
$o = studyplan::add([
'name' => $name,
'shortname' => $shortname,
2023-08-09 12:20:05 +02:00
'idnumber' => $idnumber,
'description' => $description,
2023-08-03 18:44:57 +02:00
'periods' => $periods,
'startdate' => $startdate,
2023-08-25 10:41:56 +02:00
'enddate' => empty($enddate) ? null : $enddate,
'aggregation' => $aggregation,
2023-08-25 09:33:42 +02:00
'aggregation_config' => $aggregationconfig,
'context_id' => $contextid,
]);
return $o->simple_model();
}
2023-08-24 23:02:41 +02:00
/************************
* *
* edit_studyplan *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function edit_studyplan
*/
2023-08-28 08:51:52 +02:00
public static function edit_studyplan_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"id" => new \external_value(PARAM_INT, 'id of studyplan'),
"name" => new \external_value(PARAM_TEXT, 'name of studyplan'),
2023-08-25 10:41:56 +02:00
"shortname" => new \external_value(PARAM_TEXT, 'shortname of studyplan'),
"idnumber" => new \external_value(PARAM_TEXT, 'idnumber of studyplan'),
"description" => new \external_value(PARAM_TEXT, 'description of studyplan'),
2023-08-03 18:44:57 +02:00
"periods" => new \external_value(PARAM_INT, 'number of periods in studyplan'),
"startdate" => new \external_value(PARAM_TEXT, 'start date of studyplan'),
"enddate" => new \external_value(PARAM_TEXT, 'end date of studyplan'),
2023-08-24 23:02:41 +02:00
"aggregation" => new \external_value(PARAM_TEXT, 'selected aggregator', VALUE_DEFAULT),
"aggregation_config" => new \external_value(PARAM_TEXT, 'config string for aggregator', VALUE_DEFAULT),
"context_id" => new \external_value(PARAM_INT, 'context of the study plan', VALUE_DEFAULT),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function edit_studyplan
*/
2023-08-28 11:26:14 +02:00
public static function edit_studyplan_returns() : \external_description {
return studyplan::simple_structure();
}
2023-08-24 23:02:41 +02:00
2023-08-27 23:27:07 +02:00
/**
* Edit studyplan parameters
* @param mixed $id
* @param mixed $name
* @param mixed $shortname
* @param mixed $idnumber
* @param mixed $description
* @param mixed $periods
* @param mixed $startdate
* @param mixed $enddate
* @param string $aggregation
* @param string $aggregationconfig
* @param int $contextid
* @return array
*/
2023-08-25 11:52:05 +02:00
public static function edit_studyplan($id, $name, $shortname, $idnumber, $description, $periods, $startdate,
2023-08-25 13:04:19 +02:00
$enddate, $aggregation = "bistate", $aggregationconfig = '', $contextid = 0) {
2023-08-24 23:02:41 +02:00
// Validate access in the intended context.
2023-08-25 09:33:42 +02:00
$context = webservicehelper::find_context($contextid);
2023-08-25 11:52:05 +02:00
// Do not validate the context in this case, just check the permissions.
webservicehelper::require_capabilities(self::CAP_EDIT, $context, false);
2023-08-25 17:33:20 +02:00
$o = studyplan::find_by_id($id);
2023-08-24 23:02:41 +02:00
webservicehelper::require_capabilities(self::CAP_EDIT, $o->context());
$o->edit([
'name' => $name,
'shortname' => $shortname,
2023-08-09 12:20:05 +02:00
'idnumber' => $idnumber,
'description' => $description,
2023-08-03 18:44:57 +02:00
'periods' => $periods,
'startdate' => $startdate,
'enddate' => $enddate,
'aggregation' => $aggregation,
2023-08-25 09:33:42 +02:00
'aggregation_config' => $aggregationconfig,
'context_id' => $contextid,
]);
return $o->simple_model();
}
/************************
* *
* delete_studyplan *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function delete_studyplan
*/
2023-08-28 08:51:52 +02:00
public static function delete_studyplan_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"id" => new \external_value(PARAM_INT, 'id of studyplan'),
"force" => new \external_value(PARAM_BOOL, 'id of studyplan', VALUE_DEFAULT),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function delete_studyplan
*/
2023-08-28 11:26:14 +02:00
public static function delete_studyplan_returns() : \external_description {
return success::structure();
}
2023-08-24 23:02:41 +02:00
2023-08-27 23:27:07 +02:00
/**
* Delete a studyplan
* @param mixed $id Id of the studyplan
* @param bool $force Force deletion, even though studyplan is not empty
* @return array Succes/fail model
*/
2023-08-25 13:04:19 +02:00
public static function delete_studyplan($id, $force = false) {
2023-08-25 17:33:20 +02:00
$o = studyplan::find_by_id($id);
2023-08-25 09:44:34 +02:00
// Validate if the requesting user has the right to edit the plan in it's current context.
2023-08-24 23:02:41 +02:00
webservicehelper::require_capabilities(self::CAP_EDIT, $o->context());
return $o->delete(!!$force)->model();
}
/************************
* *
* add_studyline *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function add_studyline
*/
2023-08-28 08:51:52 +02:00
public static function add_studyline_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"page_id" => new \external_value(PARAM_INT, 'id of studyplan to add line to'),
"name" => new \external_value(PARAM_TEXT, 'shortname of studyline'),
2023-08-25 10:41:56 +02:00
"shortname" => new \external_value(PARAM_TEXT, 'idnumber of studyline'),
"color" => new \external_value(PARAM_TEXT, 'description of studyline'),
"sequence" => new \external_value(PARAM_INT, 'sequence of studyline'),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function add_studyline
*/
2023-08-28 11:26:14 +02:00
public static function add_studyline_returns() : \external_description {
return studyline::editor_structure();
}
2023-08-24 23:02:41 +02:00
2023-08-27 23:27:07 +02:00
/**
* Add a new study line
* @param mixed $pageid
* @param mixed $name
* @param mixed $shortname
* @param mixed $color
* @param mixed $sequence
* @return array
*/
2023-08-25 09:33:42 +02:00
public static function add_studyline($pageid, $name, $shortname, $color, $sequence) {
2023-08-25 09:44:34 +02:00
// Validate if the requesting user has the right to edit the plan in it's current context.
2023-08-25 17:33:20 +02:00
$page = studyplanpage::find_by_id($pageid);
2023-08-24 23:02:41 +02:00
webservicehelper::require_capabilities(self::CAP_EDIT, $page->studyplan()->context());
$o = studyline::add([
2023-08-25 09:33:42 +02:00
'page_id' => $pageid,
'name' => $name,
'shortname' => $shortname,
'color' => $color,
'sequence' => $sequence,
]);
return $o->editor_model();
}
/************************
* *
* edit_studyline *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function edit_studyline
*/
2023-08-28 08:51:52 +02:00
public static function edit_studyline_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"id" => new \external_value(PARAM_INT, 'id of studyline'),
"name" => new \external_value(PARAM_TEXT, 'shortname of studyline'),
2023-08-25 10:41:56 +02:00
"shortname" => new \external_value(PARAM_TEXT, 'idnumber of studyline'),
"color" => new \external_value(PARAM_TEXT, 'description of studyline'),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function edit_studyline
*/
2023-08-28 11:26:14 +02:00
public static function edit_studyline_returns() : \external_description {
return studyline::editor_structure();
}
2023-08-24 23:02:41 +02:00
2023-08-27 23:27:07 +02:00
/**
* Edit studyline parameters
* @param mixed $id
* @param mixed $name
* @param mixed $shortname
* @param mixed $color
* @return [type]
*/
2023-08-24 23:02:41 +02:00
public static function edit_studyline($id, $name, $shortname, $color) {
2023-08-25 17:33:20 +02:00
$o = studyline::find_by_id($id);
2023-08-25 09:44:34 +02:00
// Validate if the requesting user has the right to edit the plan in it's current context.
2023-08-24 23:02:41 +02:00
webservicehelper::require_capabilities(self::CAP_EDIT, $o->context());
$o->edit([
'name' => $name,
'shortname' => $shortname,
'color' => $color,
]);
return $o->editor_model();
}
/************************
* *
* delete_studyline *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function delete_studyline
*/
2023-08-28 08:51:52 +02:00
public static function delete_studyline_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"id" => new \external_value(PARAM_INT, 'id of studyline'),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function delete_studyline
*/
2023-08-28 11:26:14 +02:00
public static function delete_studyline_returns() : \external_description {
return success::structure();
}
2023-08-24 23:02:41 +02:00
2023-08-27 23:27:07 +02:00
/**
* Delete a study line
* @param mixed $id Id of the studyline
* @return array Success/fail model
2023-08-27 23:29:46 +02:00
*
2023-08-27 23:27:07 +02:00
*/
2023-08-24 23:02:41 +02:00
public static function delete_studyline($id) {
2023-08-25 17:33:20 +02:00
$o = studyline::find_by_id($id);
2023-08-25 09:44:34 +02:00
// Validate if the requesting user has the right to edit the plan in it's current context.
2023-08-24 23:02:41 +02:00
webservicehelper::require_capabilities(self::CAP_EDIT, $o->context());
return $o->delete()->model();
}
/************************
* *
* reorder_studylines *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function reorder_studylines
*/
2023-08-28 08:51:52 +02:00
public static function reorder_studylines_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"sequence" => new \external_multiple_structure(
new \external_single_structure([
"id" => new \external_value(PARAM_INT, 'id of studyline '),
"sequence" => new \external_value(PARAM_INT, 'order of studyline'),
]),
),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function reorder_studylines
*/
2023-08-28 11:26:14 +02:00
public static function reorder_studylines_returns() : \external_description {
return success::structure();
}
2023-08-24 23:02:41 +02:00
2023-08-27 23:27:07 +02:00
/**
* Reorder study lines
* @param int[] $resequence New order of study lines by id
2023-08-28 11:26:14 +02:00
* @return array
2023-08-27 23:27:07 +02:00
*/
2023-08-24 23:02:41 +02:00
public static function reorder_studylines($resequence) {
2023-08-25 09:44:34 +02:00
// Validate if the requesting user has the right to edit the lines in it's current context.
2023-08-24 23:02:41 +02:00
foreach ($resequence as $sq) {
2023-08-25 17:33:20 +02:00
$o = studyline::find_by_id(($sq['id']));
2023-08-24 23:02:41 +02:00
webservicehelper::require_capabilities(self::CAP_EDIT, $o->context());
}
return studyline::reorder($resequence)->model();
}
2023-08-24 23:02:41 +02:00
2023-08-25 13:04:19 +02:00
/***********************************
* STUDYITEM FUNCTIONS
***********************************/
/************************
* *
2023-08-25 13:04:19 +02:00
* get_studyitem *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function get_studyitem
*/
2023-08-28 08:51:52 +02:00
public static function get_studyitem_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"id" => new \external_value(PARAM_INT, 'id of a study item to retrieve'),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function get_studyitem
*/
2023-08-28 11:26:14 +02:00
public static function get_studyitem_returns() : \external_description {
return studyitem::editor_structure();
}
2023-08-27 23:27:07 +02:00
/**
* Get editor model for study item
* @param mixed $id ID of study item
* @return array
*/
2023-08-24 23:02:41 +02:00
public static function get_studyitem($id) {
2023-08-25 17:33:20 +02:00
$o = studyitem::find_by_id($id);
2023-08-24 23:02:41 +02:00
webservicehelper::require_capabilities([self::CAP_EDIT, self::CAP_VIEW], $o->context());
return $o->editor_model();
}
2023-08-24 23:02:41 +02:00
/************************
* *
* add_studyitem *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function add_studyitem
*/
2023-08-28 08:51:52 +02:00
public static function add_studyitem_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"line_id" => new \external_value(PARAM_INT, 'id of related study line'),
"type" => new \external_value(PARAM_TEXT, 'type of study item'),
"details" => new \external_single_structure([
2023-08-25 10:41:56 +02:00
"conditions" => new \external_value(PARAM_TEXT, 'conditions for completion', VALUE_OPTIONAL),
2023-08-24 23:02:41 +02:00
"competency_id" => new \external_value(PARAM_INT, 'id of referenced competency', VALUE_OPTIONAL),
"course_id" => new \external_value(PARAM_INT, 'id of referenced course', VALUE_OPTIONAL),
"badge_id" => new \external_value(PARAM_INT, 'id of referenced badge', VALUE_OPTIONAL),
"continuation_id" => new \external_value(PARAM_INT, 'id of continued item', VALUE_OPTIONAL),
]),
2023-08-24 23:02:41 +02:00
"slot" => new \external_value(PARAM_INT, 'slot in the study plan', VALUE_DEFAULT),
"layer" => new \external_value(PARAM_INT, 'layer in the slot', VALUE_OPTIONAL),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function add_studyitem
*/
2023-08-28 11:26:14 +02:00
public static function add_studyitem_returns() : \external_description {
return studyitem::editor_structure();
}
2023-08-27 23:27:07 +02:00
/**
* Add a new study item
* @param int $lineid
2023-08-27 23:29:46 +02:00
* @param string $type
2023-08-27 23:27:07 +02:00
* @param array $details
* @param int $slot
* @param int $layer
* @return array
*/
2023-08-25 13:04:19 +02:00
public static function add_studyitem($lineid, $type, $details, $slot = -1, $layer = 0) {
2023-08-25 17:33:20 +02:00
webservicehelper::require_capabilities(self::CAP_EDIT, studyline::find_by_id($lineid)->context());
$o = studyitem::add([
2023-08-25 09:33:42 +02:00
'line_id' => $lineid,
'type' => $type,
'slot' => $slot,
2023-07-15 22:00:17 +02:00
'layer' => $layer,
2023-08-25 10:41:56 +02:00
'competency_id' => isset($details['competency_id']) ? $details['competency_id'] : null,
'course_id' => isset($details['course_id']) ? $details['course_id'] : null,
'badge_id' => isset($details['badge_id']) ? $details['badge_id'] : null,
'continuation_id' => isset($details['continuation_id']) ? $details['continuation_id'] : null,
]);
return $o->editor_model();
}
2023-08-24 23:02:41 +02:00
/************************
* *
* edit_studyitem *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function edit_studyitem
*/
2023-08-28 08:51:52 +02:00
public static function edit_studyitem_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"id" => new \external_value(PARAM_INT, 'id of study item'),
2023-08-25 10:41:56 +02:00
"conditions" => new \external_value(PARAM_TEXT, 'conditions for completion'),
2023-08-24 23:02:41 +02:00
"continuation_id" => new \external_value(PARAM_INT, 'id of continued item', VALUE_DEFAULT),
]);
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function edit_studyitem
*/
2023-08-28 11:26:14 +02:00
public static function edit_studyitem_returns() : \external_description {
return studyitem::editor_structure();
}
2023-08-24 23:02:41 +02:00
2023-08-27 23:27:07 +02:00
/**
* Edit study item paremeters
* @param mixed $id Id of studt item
* @param mixed $conditions Conditions related to item (filters only)
* @param bool $continuationid Link to previous filter item to copy result from (not used)
* @return array
*/
2023-08-25 13:04:19 +02:00
public static function edit_studyitem($id, $conditions, $continuationid = false) {
2023-08-24 23:02:41 +02:00
2023-08-25 17:33:20 +02:00
$o = studyitem::find_by_id($id);
2023-08-24 23:02:41 +02:00
webservicehelper::require_capabilities(self::CAP_EDIT, $o->context());
$config = [
'conditions' => $conditions,
];
2023-08-25 09:33:42 +02:00
if ($continuationid !== false) {
$config['continuation_id'] = $continuationid;
}
$o->edit($config);
return $o->editor_model();
}
/************************
* *
* reorder_studyitems *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function reorder_studyitems
*/
2023-08-28 08:51:52 +02:00
public static function reorder_studyitems_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"items" => new \external_multiple_structure(
new \external_single_structure([
"id" => new \external_value(PARAM_INT, 'id of studyitem '),
"line_id" => new \external_value(PARAM_INT, 'id of related study line'),
"slot" => new \external_value(PARAM_INT, 'slot in the study plan'),
"layer" => new \external_value(PARAM_INT, 'layer in the slot'),
]),
),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function reorder_studyitems
*/
2023-08-28 11:26:14 +02:00
public static function reorder_studyitems_returns() : \external_description {
return success::structure();
}
2023-08-24 23:02:41 +02:00
2023-08-27 23:27:07 +02:00
/**
* Reposition study items in line, layer and/or slot
* @param mixed $resequence Array of item info [id, line_id, slot, layer]
* @return array Success/fail model
*/
2023-08-24 23:02:41 +02:00
public static function reorder_studyitems($resequence) {
// Check for permissions to modify the studyplan.
foreach ($resequence as $sq) {
2023-08-25 17:33:20 +02:00
webservicehelper::require_capabilities(self::CAP_EDIT, studyitem::find_by_id(($sq['id']))->context());
}
return studyitem::reorder($resequence)->model();
}
/************************
* *
* delete_studyitem *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function delete_studyitem
*/
2023-08-28 08:51:52 +02:00
public static function delete_studyitem_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"id" => new \external_value(PARAM_INT, 'id of studyitem'),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function delete_studyitem
*/
2023-08-28 11:26:14 +02:00
public static function delete_studyitem_returns() : \external_description {
return success::structure();
}
2023-08-24 23:02:41 +02:00
2023-08-27 23:27:07 +02:00
/**
* Delete a studyitem
* @param mixed $id Id of study item to delete
* @return array Success/fail model
*/
2023-08-24 23:02:41 +02:00
public static function delete_studyitem($id) {
2023-08-25 17:33:20 +02:00
$o = studyitem::find_by_id($id);
2023-08-24 23:02:41 +02:00
webservicehelper::require_capabilities(self::CAP_EDIT, $o->context());
return $o->delete()->model();
}
/************************
* *
* connect_studyitems *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function connect_studyitems
*/
2023-08-28 08:51:52 +02:00
public static function connect_studyitems_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"from_id" => new \external_value(PARAM_INT, 'id of studyitem connect start '),
"to_id" => new \external_value(PARAM_INT, 'id ofstudyitem connect end'),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function connect_studyitems
*/
2023-08-28 11:26:14 +02:00
public static function connect_studyitems_returns() : \external_description {
return studyitemconnection::structure();
}
2023-08-27 23:27:07 +02:00
/**
* Connect two studylines
* @param mixed $fromid Originating item
* @param mixed $toid Target item
* @return array Success/fail model
*/
2023-08-25 09:33:42 +02:00
public static function connect_studyitems($fromid, $toid) {
2023-08-24 23:02:41 +02:00
// Validate permissions.
2023-08-25 17:33:20 +02:00
webservicehelper::require_capabilities(self::CAP_EDIT, studyitem::find_by_id($fromid)->context());
webservicehelper::require_capabilities(self::CAP_EDIT, studyitem::find_by_id($toid)->context());
2023-08-24 23:02:41 +02:00
2023-08-25 09:33:42 +02:00
$o = studyitemconnection::connect($fromid, $toid);
return $o->model();
}
/****************************
* *
* disconnect_studyitems *
* *
****************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function disconnect_studyitems
*/
2023-08-28 08:51:52 +02:00
public static function disconnect_studyitems_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"from_id" => new \external_value(PARAM_INT, 'id of studyitem '),
"to_id" => new \external_value(PARAM_INT, 'id of related study line'),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function disconnect_studyitems
*/
2023-08-28 11:26:14 +02:00
public static function disconnect_studyitems_returns() : \external_description {
return success::structure();
}
2023-08-24 23:02:41 +02:00
2023-08-27 23:27:07 +02:00
/**
* Disconnect two studylines
* @param mixed $fromid Originating item
* @param mixed $toid Target item
* @return array Success/fail model
*/
2023-08-25 09:33:42 +02:00
public static function disconnect_studyitems($fromid, $toid) {
2023-08-24 23:02:41 +02:00
// Validate permissions.
2023-08-25 17:33:20 +02:00
webservicehelper::require_capabilities(self::CAP_EDIT, studyitem::find_by_id($fromid)->context());
webservicehelper::require_capabilities(self::CAP_EDIT, studyitem::find_by_id($toid)->context());
2023-08-25 09:33:42 +02:00
return studyitemconnection::disconnect($fromid, $toid)->model();
2023-08-24 23:02:41 +02:00
}
/****************************
* *
* list badges *
* *
****************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function list_badges
*/
2023-08-28 08:51:52 +02:00
public static function list_badges_parameters() : \external_function_parameters {
return new \external_function_parameters( [] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function list_badges
*/
2023-08-28 11:26:14 +02:00
public static function list_badges_returns() : \external_description {
return new \external_multiple_structure(badgeinfo::editor_structure());
}
2023-08-24 23:02:41 +02:00
2023-08-27 23:27:07 +02:00
/**
* List all available badges to drag into a studyplan page
* @return array
*/
2023-08-24 23:02:41 +02:00
public static function list_badges() {
$systemcontext = webservicehelper::system_context();
$result = [];
2023-08-24 23:02:41 +02:00
$badges = badges_get_badges(BADGE_TYPE_SITE, "timemodified");
foreach ($badges as $badge) {
2023-08-25 13:04:19 +02:00
// TODO: Add config option to list only active badges.
$result[] = (new badgeinfo($badge))->editor_model();
2023-08-25 13:04:19 +02:00
// TODO: Include course badges somehow... Just site badges is not enough.
2023-08-24 23:02:41 +02:00
}
return $result;
2023-08-24 23:02:41 +02:00
}
/****************************
* *
* include/remove grades *
* *
****************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function include_grade
*/
2023-08-28 08:51:52 +02:00
public static function include_grade_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"grade_id" => new \external_value(PARAM_INT, 'id of gradeitem '),
"item_id" => new \external_value(PARAM_INT, 'id of studyitem '),
"include" => new \external_value(PARAM_BOOL, 'include or not '),
"required" => new \external_value(PARAM_BOOL, 'required grade or not', VALUE_DEFAULT),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function include_grade
*/
2023-08-28 11:26:14 +02:00
public static function include_grade_returns() : \external_description {
return success::structure();
}
2023-08-24 23:02:41 +02:00
2023-08-27 23:27:07 +02:00
/**
* Mark a gradable item for inclusion in the studyplan
* @param mixed $gradeid Id of gradable
* @param mixed $itemid Id of study item
* @param bool $include Include grade or not
* @param bool $required Mark grade as required or not
* @return array Success/Fail model
2023-08-27 23:29:46 +02:00
*
2023-08-27 23:27:07 +02:00
*/
2023-08-25 13:04:19 +02:00
public static function include_grade($gradeid, $itemid, $include, $required = false) {
global $USER;
2023-08-25 09:44:34 +02:00
// Find related course and course context.
2023-08-25 17:33:20 +02:00
$coursecontext = gradeinfo::get_coursecontext_by_id($gradeid);
2023-08-25 09:44:34 +02:00
// Do sanity checks.
\external_api::validate_context($coursecontext);
2023-08-25 09:44:34 +02:00
// Check correct capabilities.
2023-08-25 17:33:20 +02:00
if (has_capability('local/treestudyplan:editstudyplan', studyitem::find_by_id($itemid)->context()) ||
2023-08-24 23:02:41 +02:00
is_enrolled($coursecontext, $USER, 'local/treestudyplan:selectowngradables')) {
2023-08-25 09:33:42 +02:00
return gradeinfo::include_grade($gradeid, $itemid, $include, $required)->model();
2023-08-24 23:09:20 +02:00
} else {
return success::fail("Access denied")->model();
}
2023-08-24 23:02:41 +02:00
}
/****************************************
* *
* mark/unmark competency required *
* *
****************************************/
/**
* Parameter description for webservice function require_competency
*/
public static function require_competency_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"competency_id" => new \external_value(PARAM_INT, 'id of competency '),
"item_id" => new \external_value(PARAM_INT, 'id of studyitem '),
"required" => new \external_value(PARAM_BOOL, 'required grade or not', VALUE_DEFAULT),
] );
}
/**
* Return value description for webservice function require_competency
*/
public static function require_competency_returns() : \external_description {
return success::structure();
}
/**
* Mark a competency as required for course completion
* @param mixed $gradeid Id of gradable
* @param mixed $itemid Id of study item
* @param bool $required Mark grade as required or not
* @return array Success/Fail model
*
*/
public static function require_competency($competencyid, $itemid, $required) {
global $USER;
$item = studyitem::find_by_id($itemid);
// Find related course and course context.
if($item->courseid()) {
$coursecontext = \context_course::instance($item->courseid());
// Do sanity checks.
\external_api::validate_context($coursecontext);
} else {
$coursecontext = null;
\external_api::validate_context($item->context());
}
// Check correct capabilities.
if (has_capability('local/treestudyplan:editstudyplan', $item->context()) ||
($coursecontext && is_enrolled($coursecontext, $USER, 'local/treestudyplan:selectowngradables'))) {
return coursecompetencyinfo::require_competency($competencyid, $itemid, $required)->model();
} else {
return success::fail("Access denied")->model();
}
}
/****************************
* *
* list aggregators *
* *
****************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function list_aggregators
*/
2023-08-28 08:51:52 +02:00
public static function list_aggregators_parameters() : \external_function_parameters {
return new \external_function_parameters([]);
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function list_aggregators
*/
2023-08-28 11:26:14 +02:00
public static function list_aggregators_returns() : \external_description {
return aggregator::list_structure();
}
2023-08-24 23:02:41 +02:00
2023-08-27 23:27:07 +02:00
/**
* List available aggregators
* @return array
*/
2023-08-24 23:02:41 +02:00
public static function list_aggregators() {
return aggregator::list_model();
2023-08-24 23:02:41 +02:00
}
/****************************
* *
* force_studyplan_scale *
* *
****************************/
2023-08-24 23:02:41 +02:00
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function force_studyplan_scale
*/
2023-08-28 08:51:52 +02:00
public static function force_studyplan_scale_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan'),
"scale_id" => new \external_value(PARAM_INT, 'scale_id to set'),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function force_studyplan_scale
*/
2023-08-28 08:51:52 +02:00
public static function force_studyplan_scale_returns() : \external_description {
return new \external_multiple_structure(new \external_single_structure([
"course" => courseinfo::simple_structure(),
"grades" => new \external_multiple_structure(new \external_single_structure([
"name" => new \external_value(PARAM_TEXT, 'grade name'),
"changed" => new \external_value(PARAM_TEXT, 'changed or not'),
2023-08-24 23:02:41 +02:00
"debug" => new \external_value(PARAM_TEXT, 'debug', VALUE_OPTIONAL),
])),
]));
}
2023-08-24 23:02:41 +02:00
2023-08-27 23:27:07 +02:00
/**
* Force all gradables in the studyplan to the same scale item
* @param int $studyplanid Id of studyplan
* @param int $scaleid Id of scale to use
* @return array
*/
2023-08-27 23:29:46 +02:00
public static function force_studyplan_scale($studyplanid, $scaleid) {
global $DB;
$dbman = $DB->get_manager();
2023-08-24 23:02:41 +02:00
// Validate permissions.
2023-08-25 17:33:20 +02:00
webservicehelper::require_capabilities(self::CAP_EDIT, studyplan::find_by_id($studyplanid)->context());
$list = [];
2023-08-25 09:44:34 +02:00
// Check if scaleid is valid.
2023-08-25 09:33:42 +02:00
$scale = \grade_scale::fetch(['id' => $scaleid]);
$scale->load_items();
2023-08-24 23:02:41 +02:00
if ($scale) {
2023-08-25 10:41:56 +02:00
$gradecfg = $DB->get_record("local_treestudyplan_gradecfg", ["scale_id" => $scale->id]);
$scalepass = ($gradecfg) ? $gradecfg->min_completed : 0;
$scalemax = count($scale->scale_items);
2023-08-25 09:44:34 +02:00
// Find studyline id's.
2023-08-25 11:52:05 +02:00
$studylineids = $DB->get_fieldset_select(studyline::TABLE, "id",
"studyplan_id = :plan_id", ['plan_id' => $studyplanid]);
2023-08-25 09:33:42 +02:00
foreach ($studylineids as $studylineid) {
2023-08-25 09:44:34 +02:00
// Find id's of studyitems of type course.
2023-08-25 09:33:42 +02:00
$records = $DB->get_records(studyitem::TABLE, ['line_id' => $studylineid]);
2023-08-25 09:33:42 +02:00
foreach ($records as $itemr) {
$studyitem = new studyitem($itemr->id);
2023-08-25 17:33:20 +02:00
if ($studyitem->valid() && $studyitem->type() == studyitem::COURSE) {
$courseinfo = $studyitem->getcourseinfo();
$gradables = gradeinfo::list_studyitem_gradables($studyitem);
2023-08-24 23:02:41 +02:00
$gradelist = [];
2023-08-24 23:02:41 +02:00
foreach ($gradables as $g) {
2023-08-25 17:33:20 +02:00
$gi = $g->get_gradeitem();
2023-08-24 23:02:41 +02:00
2023-08-25 09:44:34 +02:00
// Only change items that do not yet have grades.
// Otherwise we will need to implement grade recalculations and it is not worth the trouble. .
// If grades are given, you likely don't want to change it like this anyway.
2023-08-24 23:02:41 +02:00
if (!$gi->has_grades()) {
$gi->gradetype = GRADE_TYPE_SCALE;
$gi->scaleid = $scale->id;
$gi->grademin = 1;
$gi->grademax = $scalemax;
2023-08-24 23:02:41 +02:00
$gi->gradepass = $scalepass;
2023-08-25 11:52:05 +02:00
// Update, signalling with our signature and bulkupdate.
$result = $gi->update("local/treestudyplan");
$debug = "";
2023-08-25 10:41:56 +02:00
if ($result) {
$updated = "converted";
2023-08-25 11:52:05 +02:00
} else {
2023-08-25 10:41:56 +02:00
$updated = "error";
}
2023-08-25 09:44:34 +02:00
// Next update the activity's table if it has a grade field.
// Grade is generally set to the negative scale id if it is a scale.
$tablename = $gi->itemmodule;
$fieldname = "grade";
2023-08-24 23:02:41 +02:00
if ($result && $gi->itemtype == "mod" && $dbman->table_exists($tablename)) {
if ($dbman->field_exists($tablename, $fieldname)) {
2023-08-25 13:04:19 +02:00
$gradevalue = intval(0 - ($scale->id));
try {
2023-08-25 09:33:42 +02:00
$DB->set_field($tablename, $fieldname, $gradevalue, ["id" => $gi->iteminstance]);
2023-08-25 10:41:56 +02:00
} catch (\dml_exception $x) {
$updated = "fail";
$debug = strval($x);
}
}
}
2023-08-24 23:02:41 +02:00
2023-08-24 23:09:20 +02:00
} else {
$updated = "skipped";
}
$gradelist[] = [
'name' => $gi->itemname,
'changed' => $updated,
'debug' => $debug,
];
}
$list[] = [
'course' => $courseinfo->simple_model(),
'grades' => $gradelist,
];
}
}
}
}
return $list;
2023-08-24 23:02:41 +02:00
}
/****************************
* *
* list_scales *
* *
****************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function list_scales
*/
2023-08-28 08:51:52 +02:00
public static function list_scales_parameters() : \external_function_parameters {
return new \external_function_parameters( [] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function list_scales
*/
2023-08-28 11:26:14 +02:00
public static function list_scales_returns() : \external_description {
return new \external_multiple_structure(new \external_single_structure([
"id" => new \external_value(PARAM_INT, 'id of scale'),
"name" => new \external_value(PARAM_TEXT, 'scale name'),
]));
}
2023-08-24 23:02:41 +02:00
2023-08-27 23:27:07 +02:00
/**
* List available scales
* @return array
*/
2023-08-24 23:02:41 +02:00
public static function list_scales() {
global $DB;
$list = [];
$scales = \grade_scale::fetch_all_global();
2023-08-24 23:02:41 +02:00
foreach ($scales as $scale) {
$list[] = [
"id" => $scale->id,
"name" => $scale->name,
];
}
return $list;
2023-08-24 23:02:41 +02:00
}
/****************************
* *
* duplicate studyplan *
* *
****************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function duplicate_plan
*/
2023-08-28 08:51:52 +02:00
public static function duplicate_plan_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"plan_id" => new \external_value(PARAM_INT, 'id of plan to copy '),
"name" => new \external_value(PARAM_TEXT, 'name of copy '),
"shortname" => new \external_value(PARAM_TEXT, 'shortname of copy '),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function duplicate_plan
*/
2023-08-28 11:26:14 +02:00
public static function duplicate_plan_returns() : \external_description {
return studyplan::simple_structure();
}
2023-08-27 23:27:07 +02:00
/**
* Duplicate a studyplan into a new one
* @param mixed $studyplanid Id of the plan to duplicate
* @param mixed $name New fullname
* @param mixed $shortname New shortname
* @return array
*/
2023-08-25 09:33:42 +02:00
public static function duplicate_plan($studyplanid, $name, $shortname) {
2023-08-24 23:02:41 +02:00
// Validate permissions.
2023-08-25 17:33:20 +02:00
webservicehelper::require_capabilities(self::CAP_EDIT, studyplan::find_by_id($studyplanid)->context());
2023-08-24 23:02:41 +02:00
2023-08-25 09:33:42 +02:00
return studyplan::duplicate_plan($studyplanid, $name, $shortname);
2023-08-24 23:02:41 +02:00
}
/****************************
* *
* export studyplan *
* *
****************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function export_plan
*/
2023-08-28 08:51:52 +02:00
public static function export_plan_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"studyplan_id" => new \external_value(PARAM_INT, 'id of plan to export '),
2023-08-24 23:02:41 +02:00
"format" => new \external_value(PARAM_TEXT, 'export format', VALUE_OPTIONAL),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function export_plan
*/
2023-08-28 11:26:14 +02:00
public static function export_plan_returns() : \external_description {
return studyplan::export_structure();
}
2023-08-24 23:02:41 +02:00
2023-08-27 23:29:46 +02:00
2023-08-27 23:27:07 +02:00
/**
2023-08-27 23:29:46 +02:00
* Export studyplan
2023-08-27 23:27:07 +02:00
* @param mixed $studyplanid Id of studyplan to export
* @param string $format Export format [csv, json (default)]
* @return array
*/
2023-08-25 13:04:19 +02:00
public static function export_plan($studyplanid, $format = "json") {
2023-08-24 23:09:20 +02:00
try {
2023-08-24 23:02:41 +02:00
// Validate permissions.
2023-08-25 17:33:20 +02:00
webservicehelper::require_capabilities(self::CAP_EDIT, studyplan::find_by_id($studyplanid)->context());
2023-08-25 17:33:20 +02:00
$plan = studyplan::find_by_id($studyplanid);
2023-11-11 20:17:45 +01:00
return $plan->export_plan();
2023-08-25 10:41:56 +02:00
} catch (\webservice_access_exception $x) {
return [ "format" => "", "content" => ""];
}
2023-08-24 23:02:41 +02:00
}
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function export_studylines
*/
2023-11-11 20:17:45 +01:00
public static function export_page_parameters() : \external_function_parameters {
return new \external_function_parameters( [
2023-11-11 20:17:45 +01:00
"page_id" => new \external_value(PARAM_INT, 'id of plan to export '),
"format" => new \external_value(PARAM_TEXT, 'export format', VALUE_OPTIONAL),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function export_studylines
*/
2023-11-11 20:17:45 +01:00
public static function export_page_returns() : \external_description {
return studyplanpage::export_structure();
}
2023-08-24 23:02:41 +02:00
2023-08-27 23:27:07 +02:00
/**
* Export studylines for a studyplan
* @param mixed $studyplanid Id of the studyplan to export the studylines for
2023-11-11 20:17:45 +01:00
* @param string $format Export format [csv, json (default)]
2023-08-27 23:27:07 +02:00
* @return array
*/
2023-11-11 20:17:45 +01:00
public static function export_page($pageid,$format="json") {
2023-08-24 23:09:20 +02:00
try {
2023-11-11 20:17:45 +01:00
$page = studyplanpage::find_by_id($pageid);
webservicehelper::require_capabilities(self::CAP_EDIT, $page->studyplan()->context());
if ($format == "csv") {
return $page->export_page_csv();
} else {
return $page->export_page();
}
2023-08-25 10:41:56 +02:00
} catch (\webservice_access_exception $x) {
return [ "format" => "", "content" => ""];
}
2023-08-24 23:02:41 +02:00
}
2023-11-11 20:17:45 +01:00
/****************************
* *
* import studyplan *
* *
****************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function import_plan
*/
2023-08-28 08:51:52 +02:00
public static function import_plan_parameters() : \external_function_parameters {
return new \external_function_parameters( [
2023-11-11 20:17:45 +01:00
"content" => new \external_value(PARAM_RAW, 'import file content'),
"format" => new \external_value(PARAM_TEXT, 'import format'),
2023-08-24 23:02:41 +02:00
"context_id" => new \external_value(PARAM_INT, 'context of the study plan', VALUE_DEFAULT),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function import_plan
*/
2023-08-28 11:26:14 +02:00
public static function import_plan_returns() : \external_description {
return success::structure();
}
2023-08-24 23:02:41 +02:00
2023-08-27 23:27:07 +02:00
/**
* Import studyplan from file
2023-08-27 23:29:46 +02:00
* @param string $content Content of file
2023-08-27 23:27:07 +02:00
* @param string $format Format of file
* @param int $contextid ID of context to import to
* @return array Success/fail model
*/
2023-08-25 13:04:19 +02:00
public static function import_plan($content, $format = "application/json", $contextid = 1) {
2023-08-24 23:09:20 +02:00
try {
2023-08-24 23:02:41 +02:00
// Validate import context.
2023-08-25 09:33:42 +02:00
$context = webservicehelper::find_context($contextid);
2023-08-24 23:02:41 +02:00
webservicehelper::require_capabilities(self::CAP_EDIT, $context);
2023-08-25 09:33:42 +02:00
$result = studyplan::import_studyplan($content, $format, $contextid);
return (new success($result, "During study plan import"))->model();
2023-08-25 10:41:56 +02:00
} catch (\webservice_access_exception $x) {
return success::fail("Access denied")->model();
}
2023-08-24 23:02:41 +02:00
}
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function import_studylines
*/
2023-11-11 20:17:45 +01:00
public static function import_pages_parameters() : \external_function_parameters {
return new \external_function_parameters( [
2023-11-11 20:17:45 +01:00
"studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan to import to '),
"content" => new \external_value(PARAM_RAW, 'import file content'),
"format" => new \external_value(PARAM_TEXT, 'import format'),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function import_studylines
*/
2023-11-11 20:17:45 +01:00
public static function import_pages_returns() : \external_description {
return success::structure();
}
2023-08-24 23:02:41 +02:00
2023-08-27 23:27:07 +02:00
/**
* Import studylines into existing studtplan
* @param int $studyplanid ID of studyplan to import to
2023-08-27 23:29:46 +02:00
* @param string $content Content of file
2023-08-27 23:27:07 +02:00
* @param string $format Format of file
* @return array Success/fail model
*/
2023-11-11 20:17:45 +01:00
public static function import_pages($studyplanid, $content, $format = "application/json") {
2023-08-24 23:09:20 +02:00
try {
2023-08-25 17:33:20 +02:00
$plan = studyplan::find_by_id($studyplanid);
2023-08-24 23:02:41 +02:00
// Validate import context.
webservicehelper::require_capabilities(self::CAP_EDIT, $plan->context());
2023-11-11 20:17:45 +01:00
$result = $plan->import_pages($content, $format);
return ($result ? success::success() : success::fail())->model();
} catch (\webservice_access_exception $x) {
return success::fail("Access denied")->model();
}
}
/**
* Parameter description for webservice function import_studylines
*/
public static function import_studylines_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"page_id" => new \external_value(PARAM_INT, 'id of studyplan page to import to '),
"content" => new \external_value(PARAM_RAW, 'import file content'),
"format" => new \external_value(PARAM_TEXT, 'import format'),
] );
}
/**
* Return value description for webservice function import_studylines
*/
public static function import_studylines_returns() : \external_description {
return success::structure();
}
/**
* Import studylines into existing studtplan
* @param int $studyplanid ID of studyplan to import to
* @param string $content Content of file
* @param string $format Format of file
* @return array Success/fail model
*/
public static function import_studylines($page_id, $content, $format = "application/json") {
try {
$page = studyplanpage::find_by_id($page_id);
// Validate import context.
webservicehelper::require_capabilities(self::CAP_EDIT, $page->studyplan()->context());
2023-11-11 20:17:45 +01:00
$result = $page->import_studylines($content, $format);
2023-08-25 10:41:56 +02:00
return ($result ? success::success() : success::fail())->model();
} catch (\webservice_access_exception $x) {
return success::fail("Access denied")->model();
}
2023-08-24 23:02:41 +02:00
}
/********************************************************
* *
* Read and write course module title and desc *
2023-08-24 23:02:41 +02:00
* Used only in bistate aggregation method *
* *
********************************************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function submit_cm_editform
*/
2023-08-28 08:51:52 +02:00
public static function submit_cm_editform_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"cmid" => new \external_value(PARAM_INT, 'id of course module'),
"formdata" => new \external_value(PARAM_RAW, 'url encoded form data'),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function submit_cm_editform
*/
2023-08-28 11:26:14 +02:00
public static function submit_cm_editform_returns() : \external_description {
return success::structure();
}
2023-08-27 23:27:07 +02:00
/**
* Submit hacked course activity edit form to edit just name and description
2023-08-27 23:29:46 +02:00
* @deprecated will remove hacked edit form in the future
2023-08-27 23:27:07 +02:00
* @param mixed $cmid
* @param mixed $formdata
* @return array Success/fail structure
*/
2023-08-24 23:02:41 +02:00
public static function submit_cm_editform($cmid, $formdata) {
global $CFG;
global $DB;
// Check the course module exists.
$cm = \get_coursemodule_from_id('', $cmid, 0, false, MUST_EXIST);
2023-08-24 23:02:41 +02:00
// Get some context ready.
$context = \context_course::instance($cm->course);
self::validate_context($context);
// Check the course exists.
$course = \get_course($cm->course);
2023-08-25 09:44:34 +02:00
// Require_login.
2023-08-25 10:41:56 +02:00
require_login($course, false, $cm); // Needed to setup proper $COURSE.
2023-08-25 09:44:34 +02:00
// Get needed info to create the correct form.
list($cm, $context, $module, $data, $cw) = \get_moduleinfo_data($cm, $course);
$modmoodleform = "$CFG->dirroot/mod/$module->name/mod_form.php";
if (file_exists($modmoodleform)) {
require_once($modmoodleform);
} else {
2023-08-03 18:44:57 +02:00
throw new \moodle_exception('noformdesc', 'error');
}
$mformclassname = 'mod_'.$module->name.'_mod_form';
2023-08-25 09:44:34 +02:00
// Now hack the received data into $_POST, so the mform thinks it has been submitted "normally".
2023-08-24 23:02:41 +02:00
foreach (explode("&", $formdata) as $pair) {
$p = explode("=", $pair, 2);
$k = urldecode($p[0]);
2023-08-25 13:04:19 +02:00
$v = (count($p) > 1) ? urldecode($p[1]) : "";
2023-08-24 23:02:41 +02:00
2023-08-25 13:04:19 +02:00
if (strpos($k, "[") > 0 && strpos($k, "]") == strlen($k) - 1) {
2023-08-25 09:44:34 +02:00
// Its a bracketet field, like filename[text] which should be separated and put into a named array.
2023-08-24 23:02:41 +02:00
list($k, $h) = explode("[", $k, 2);
if (strlen($k) > 0 && strlen($h) > 1) {
$h = rtrim($h, "]");
if (!array_key_exists($k, $_POST) || !is_array($_POST[$k])) {
$_POST[$k] = [];
}
$_POST[$k][$h] = $v;
}
2023-08-25 13:04:19 +02:00
} else {
$_POST[$k] = $v;
}
}
2023-08-24 23:02:41 +02:00
// Now create the mform and update the module...
2023-08-25 09:44:34 +02:00
// Update_moduleinfo() actually needs the mform somehow. Hence the ugly hacks.
$mform = new $mformclassname($data, $cw->section, $cm, $course);
$mform->set_data($data);
if ($fromform = $mform->get_data()) {
update_moduleinfo($cm, $fromform, $course, $mform);
return success::success()->model();
} else {
return success::fail("MForm did not recognize submission data")->model();
}
}
2023-07-27 19:19:39 +02:00
/************************
* *
* edit_period *
* *
************************/
2023-09-03 15:21:30 +02:00
/**
* Parameter description for webservice function get_period
*/
public static function get_period_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"id" => new \external_value(PARAM_INT, 'id of study item'),
]);
}
/**
* Return value description for webservice function get_period
*/
public static function get_period_returns() : \external_description {
return period::structure();
}
/**
* Get period information
* @param mixed $id Id of period to retrieve
* @return array
*/
public static function get_period($id) {
$p = period::find_by_id($id);
2023-09-08 12:47:29 +02:00
// Public data - no rights check needed.
2023-09-03 15:21:30 +02:00
\external_api::validate_context($p->page()->studyplan()->context());
return $p->model();
}
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function edit_period
*/
2023-08-28 08:51:52 +02:00
public static function edit_period_parameters() : \external_function_parameters {
2023-08-25 13:04:19 +02:00
return new \external_function_parameters( [
"id" => new \external_value(PARAM_INT, 'id of study item'),
"fullname" => new \external_value(PARAM_TEXT, 'Full name of period'),
"shortname" => new \external_value(PARAM_TEXT, 'Short name of period'),
"startdate" => new \external_value(PARAM_TEXT, 'start date of period'),
"enddate" => new \external_value(PARAM_TEXT, 'end date of period'),
]);
}
2023-08-24 23:02:41 +02:00
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function edit_period
*/
2023-08-28 11:26:14 +02:00
public static function edit_period_returns() : \external_description {
2023-08-25 13:04:19 +02:00
return period::structure();
}
2023-08-24 23:02:41 +02:00
2023-08-27 23:27:07 +02:00
/**
* Edit period information
* @param mixed $id
* @param mixed $fullname
* @param mixed $shortname
* @param mixed $startdate
* @param mixed $enddate
* @return array
*/
2023-08-25 13:04:19 +02:00
public static function edit_period($id, $fullname, $shortname, $startdate, $enddate) {
2023-08-24 23:02:41 +02:00
2023-08-25 17:33:20 +02:00
$p = period::find_by_id($id);
2023-08-25 13:04:19 +02:00
webservicehelper::require_capabilities(self::CAP_EDIT, $p->page()->studyplan()->context());
2023-08-24 23:02:41 +02:00
2023-08-25 13:04:19 +02:00
$p->edit([
'fullname' => $fullname,
'shortname' => $shortname,
'startdate' => $startdate,
'enddate' => $enddate,
]);
return $p->model();
}
/************************
* *
* Change course timing *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function course_period_timing
*/
2023-08-28 08:51:52 +02:00
public static function course_period_timing_parameters() : \external_function_parameters {
2023-08-25 13:04:19 +02:00
return new \external_function_parameters( [
"period_id" => new \external_value(PARAM_INT, 'Period number within page'),
"course_id" => new \external_value(PARAM_INT, 'Id of course to adjust dates for'),
"span" => new \external_value(PARAM_INT, 'Period span (default 1)', VALUE_DEFAULT),
]);
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function course_period_timing
*/
2023-08-28 11:26:14 +02:00
public static function course_period_timing_returns() : \external_description {
2023-08-25 13:04:19 +02:00
return courseinfo::editor_structure();
}
2023-08-27 23:27:07 +02:00
/**
* Match course start/end to period start/end times
* @param mixed $periodid
* @param mixed $courseid
* @param int $span
* @return array
*/
2023-08-25 13:04:19 +02:00
public static function course_period_timing($periodid, $courseid, $span = 1) {
2023-08-07 23:07:59 +02:00
global $DB;
2023-08-25 17:33:20 +02:00
$period = period::find_by_id($periodid);
$periodnr = $period->period();
$page = $period->page();
2023-08-24 23:02:41 +02:00
// Check for studyplan edit permissions.
webservicehelper::require_capabilities(self::CAP_EDIT, $page->studyplan()->context());
2023-08-25 09:33:42 +02:00
$course = \get_course($courseid);
$coursecontext = \context_course::instance($courseid);
2023-08-24 23:02:41 +02:00
if (webservicehelper::has_capabilities("moodle/course:update", $coursecontext)) {
2023-08-24 23:02:41 +02:00
// Get the proper list of all the periods for this page.
2023-08-25 17:33:20 +02:00
$periods = period::find_for_page($page);
$pstart = $periods[$periodnr];
2023-08-24 23:02:41 +02:00
// Determine end period number - Clip span between 1 and last period.
if ($span <= 1) {
$pend = $pstart;
2023-08-24 23:09:20 +02:00
} else if ($periodnr + ($span - 1) > $page->periods()) {
$pend = $periods[$page->periods()];
2023-08-24 23:09:20 +02:00
} else {
$pend = $periods[$periodnr + ($span - 1)];
}
2023-08-24 23:02:41 +02:00
// First disable the automatic end date option, since it messes with the timing.
// Unfortunately there is still no default option to turn this off .
$record = $DB->get_record("course_format_options", ["courseid" => $course->id, "name" => "automaticenddate"]);
if ($record && $record->value) {
2023-08-07 23:07:59 +02:00
$record->value = false;
2023-08-24 23:02:41 +02:00
$DB->update_record("course_format_options", $record);
2023-08-07 23:07:59 +02:00
}
2023-08-24 23:02:41 +02:00
// Actually perform the timing changes, while also updating the module times.
// Like what happens on a course "reset".
reset_course_userdata((object)[
'id' => $course->id,
'reset_start_date' => $pstart->startdate()->getTimestamp(),
'reset_end_date' => $pend->enddate()->getTimestamp(),
'reset_start_date_old' => $course->startdate,
'reset_end_date_old' => $course->enddate,
]);
2023-08-25 09:44:34 +02:00
// Purge course cache so the dates are properly reflected.
\course_modinfo::purge_course_cache($course->id);
2023-08-07 23:07:59 +02:00
return (new courseinfo($course->id))->editor_model();
} else {
2023-08-25 09:44:34 +02:00
// Probably should return a nice message.
throw new \webservice_access_exception("You do not have date change permissions on this course");
}
2023-08-25 13:04:19 +02:00
}
2023-07-27 19:19:39 +02:00
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function set_studyitem_span
*/
2023-08-28 08:51:52 +02:00
public static function set_studyitem_span_parameters() : \external_function_parameters {
2023-08-25 13:04:19 +02:00
return new \external_function_parameters( [
"id" => new \external_value(PARAM_INT, 'id of study item'),
"span" => new \external_value(PARAM_INT, 'span of item'),
]);
}
2023-08-24 23:02:41 +02:00
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function set_studyitem_span
*/
2023-08-28 11:26:14 +02:00
public static function set_studyitem_span_returns() : \external_description {
2023-08-25 13:04:19 +02:00
return studyitem::editor_structure();
}
2023-08-24 23:02:41 +02:00
2023-08-27 23:27:07 +02:00
/**
* Set studyitem span to one or more periods
* @param mixed $id
* @param null $span
* @return array
*/
2023-08-25 13:04:19 +02:00
public static function set_studyitem_span($id, $span = null) {
2023-08-25 17:33:20 +02:00
$o = studyitem::find_by_id($id);
2023-08-25 13:04:19 +02:00
webservicehelper::require_capabilities(self::CAP_EDIT, $o->context());
2023-08-24 23:02:41 +02:00
2023-08-25 13:04:19 +02:00
$config = [ 'span' => $span];
$o->edit($config);
return $o->editor_model();
2023-08-24 23:02:41 +02:00
2023-08-25 13:04:19 +02:00
}
2023-11-11 20:17:45 +01:00
/************************
* *
* bulk_course_timing *
* *
************************/
/**
* Parameter description for webservice function delete_studyplan
*/
public static function bulk_course_timing_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"page_id" => new \external_value(PARAM_INT, 'id of studyplanpage'),
] );
}
/**
* Return value description for webservice function delete_studyplan
*/
public static function bulk_course_timing_returns() : \external_description {
return success::structure();
}
/**
* Delete a studyplan
* @param mixed $id Id of the studyplan
* @param bool $force Force deletion, even though studyplan is not empty
* @return array Succes/fail model
*/
public static function bulk_course_timing($pageid) {
$page = studyplanpage::find_by_id($pageid);
// Validate if the requesting user has the right to edit the plan in it's current context.
webservicehelper::require_capabilities(self::CAP_EDIT, $page->studyplan()->context());
$result = true;
$message = [];
$periods = period::find_for_page($page);
$studylines = studyline::find_page_children($page);
foreach ($studylines as $line) {
$studyitems = studyitem::find_studyline_children($line);
foreach ($studyitems as $item) {
if ($item->type() == studyitem::COURSE) {
if ( $item->slot() <= $page->periods() ) {
$period = $periods[$item->slot()];
try {
self::course_period_timing($period->id(),$item->courseid(),$item->span());
} catch (\webservice_access_exception $x) {
$result &= false;
$course = \get_course($item->courseid());
$message[] = "Course {$course->shortname}: {$x->debuginfo}";
} catch (\Exception $x) {
$result &= false;
$course = \get_course($item->courseid());
$xclass = \get_class($x);
$message[] = "Course {$course->shortname}: {$xclass} {$x->getMessage()}";
}
}
}
}
}
return (new success($result,implode("<p>\n",$message)))->model();
}
/************************
* *
* delete_studyplanpage *
* *
************************/
/**
* Parameter description for webservice function delete_studyplan
*/
public static function delete_studyplanpage_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"id" => new \external_value(PARAM_INT, 'id of studyplanpage'),
"force" => new \external_value(PARAM_BOOL, 'force deletion', VALUE_DEFAULT),
] );
}
/**
* Return value description for webservice function delete_studyplan
*/
public static function delete_studyplanpage_returns() : \external_description {
return success::structure();
}
/**
* Delete a studyplan
* @param mixed $id Id of the studyplan
* @param bool $force Force deletion, even though studyplan is not empty
* @return array Succes/fail model
*/
public static function delete_studyplanpage($id, $force = false) {
$o = studyplanpage::find_by_id($id);
$p = $o->studyplan();
// Validate if the requesting user has the right to edit the plan in it's current context.
webservicehelper::require_capabilities(self::CAP_EDIT, $p->context());
return $o->delete(!!$force)->model();
}
2023-08-25 11:52:05 +02:00
}