PHPDoc documentation

This commit is contained in:
PMKuipers 2023-08-27 15:12:54 +02:00
parent 64f9b8b043
commit 6f67e5cb84
34 changed files with 586 additions and 127 deletions

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Build script to properly create a distribution zip
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Configure how grades and scales are interpreted by the plugin if no other grade to pass is specified
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -31,6 +31,10 @@ require_capability('local/treestudyplan:configure', $systemcontext);
$PAGE->requires->js_call_amd('local_treestudyplan/cfg-grades', 'init');
/**
* Table name for gradecfg table
* @var string
*/
const GRADECFG_TABLE = "local_treestudyplan_gradecfg";
$scales = \grade_scale::fetch_all_global();

View File

@ -21,25 +21,39 @@
*/
namespace local_treestudyplan;
use \ValueError;
defined('MOODLE_INTERNAL') || die();
require_once($CFG->libdir.'/externallib.php');
abstract class aggregator {
private const FALLBACK = "bistate";
private static $modsupported = [];
private static $methodsupported = [];
public static function supported($mod) {
if (!array_key_exists($mod, self::$modsupported)) {
self::$modsupported[$mod] = class_exists(self::aggregator_name($mod));
/**
* Check if aggregation method is supported
* @param string $method Name of aggregation method
*/
public static function supported($method) {
if (!array_key_exists($method, self::$methodsupported)) {
self::$methodsupported[$method] = class_exists(self::aggregator_name($method));
}
return self::$modsupported[$mod];
return self::$methodsupported[$method];
}
private static function aggregator_name($mod) {
return "\local_treestudyplan\\local\\aggregators\\{$mod}_aggregator";
/**
* Get class name for aggregation method
* @param string $method Name of aggregation method
*/
private static function aggregator_name($method) {
return "\local_treestudyplan\\local\\aggregators\\{$method}_aggregator";
}
/**
* Get names of supported aggregation methods
* @return string[] Names of aggregation methods
*/
public static function list() {
// Static list, since we'd need to implement a lot of static data for new aggregation methods anyway.
// And this is faster than any dynamic method.
@ -50,54 +64,131 @@ abstract class aggregator {
];
}
public static function create($mod, $configstr) {
if (self::supported($mod)) {
$agclass = self::aggregator_name($mod);
/**
* Create a new aggregatior object based on the specified method
* @param mixed $method Aggregation method
* @param mixed $configstr Configuration string for aggregator
* @return self Aggregator
* @throws ValueError If method is not found
*/
public static function create($method, $configstr) {
if (self::supported($method)) {
$agclass = self::aggregator_name($method);
return new $agclass($configstr);
} else {
throw new \InvalidArgumentException("Cannot find aggregator '{$mod}'");
throw new \ValueError("Cannot find aggregator '{$method}'");
}
}
public static function createordefault($mod, $configstr) {
/**
* Create a new aggregatior object based on the specified method,
* but return a default aggregator if the method is not found
* @param mixed $method Aggregation method
* @param mixed $configstr Configuration string for aggregator
* @return self Aggregator
*/
public static function create_or_default($method, $configstr) {
try {
return self::create($mod, $configstr);
return self::create($method, $configstr);
} catch (\ValueError $x) {
return self::create(self::FALLBACK, "");
}
}
/**
* Create new instance of aggregation method
* @param string $configstr Aggregation configuration string
*/
private function __construct($configstr) {
$this->initialize($configstr);
}
/**
* Initialize the aggregation method
* @param string $configstr Aggregation configuration string
*/
protected function initialize($configstr) {
}
/**
* Determine if aggregation method wants to select gradables
* @return bool True if aggregation method needs gradables to be selected
*/
abstract public function select_gradables();
/**
* Determine if aggregation method is deprecated
* @return bool True if aggregation method is deprecated
*/
abstract public function deprecated();
/**
* Aggregate all completions in a course into one final course completion
* Possible states:
* completion::EXCELLENT - Completed with excellent results
* completion::GOOD - Completed with good results
* completion::COMPLETED - Completed
* completion::PROGRESS - Started, but not completed yey
* completion::FAILED - Failed
* completion::INCOMPLETE - Not yet started
* @param courseinfo $courseinfo Courseinfo object for the course to check
* @param studyitem $studyitem Studyitem object for the course to check
* @param int $userid Id of user to check this course for
* @return int Aggregated completion as completion class constant
*/
abstract public function aggregate_course(courseinfo $courseinfo, studyitem $studyitem, $userid);
/**
* Aggregate juncton/filter inputs into one final junction outcome
* @param int[] $completion List of completion inputs
* @param studyitem $studyitem Studyitem object for the junction
* @param int $userid Id of user to check completion for
* @return int Aggregated completion as completion class constant
*/
abstract public function aggregate_junction(array $completion, studyitem $studyitem, $userid);
/**
* Determine completion for a single grade and user
* @param gradeinfo $gradeinfo Gradeinfo object for grade to check
* @param mixed $userid Id of user to check completion for
* @return int Aggregated completion as completion class constant
*/
abstract public function grade_completion(gradeinfo $gradeinfo, $userid);
// Aggregation method makes use of "required grades" in a course/module.
/**
* Determine if Aggregation method makes use of "required grades" in a course/module.
* @return bool True if Aggregation method makes use of "required grades" in a course/module.
*/
abstract public function use_required_grades();
// Aggregation method makes use of .
/**
* Determine if aggregation method makes use of required grades
* @return bool True if aggregation method makes use of
*/
abstract public function use_item_conditions();
// Whether the aggregation method uses core_completion, or treestudyplan custom completion.
/**
* Determine if the aggregation method uses core_completion, or treestudyplan custom completion.
* @return bool True if the aggregation method uses core_completion
*/
public function usecorecompletioninfo() {
return false;
}
// Parameter editing functions - override in child class to implement parameter config for aggregation.
// Return the current configuration string.
/**
* Return the current configuration string.
* @return string Configuration string
*/
public function config_string() {
return "";
}
/**
* Webservice structure for basic aggregator info
* @param int $value Webservice requirement constant
* @return mixed Webservice output structure
*/
public static function basic_structure($value = VALUE_REQUIRED) {
return new \external_single_structure([
"useRequiredGrades" => new \external_value(PARAM_BOOL, 'id of studyplan'),
@ -105,6 +196,10 @@ abstract class aggregator {
], "Aggregator requirements", $value);
}
/**
* Webservice model for basic aggregator info
* @return array Webservice data model
*/
public function basic_model() {
return [
"useRequiredGrades" => $this->use_required_grades(),
@ -112,6 +207,11 @@ abstract class aggregator {
];
}
/**
* Webservice structure list of aggregators
* @param int $value Webservice requirement constant
* @return mixed Webservice output structure
*/
public static function list_structure($value = VALUE_REQUIRED) {
return new \external_multiple_structure(new \external_single_structure([
"id" => new \external_value(PARAM_TEXT, 'id of aggregator'),
@ -122,6 +222,10 @@ abstract class aggregator {
], "Available aggregators", $value));
}
/**
* Webservice model for list of aggregators
* @return array Webservice data model
*/
public static function list_model() {
$list = [];

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Aggregate course results based on failed/completed states for grades
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -26,13 +26,20 @@ use \local_treestudyplan\courseinfo;
use \local_treestudyplan\gradeinfo;
use \local_treestudyplan\studyitem;
use \local_treestudyplan\completion;
use \local_treestudyplan\debug;
/**
* Aggregate course results based on failed/completed states for grades
*/
class bistate_aggregator extends \local_treestudyplan\aggregator {
/** @var bool */
public const DEPRECATED = false;
/** @var stdClass */
private $agcfg = null;
/**
* Retrieve or initialize current config object
* @return stdClass
*/
private function cfg() {
if (empty($this->agcfg)) {
$this->agcfg = (object)[
@ -47,11 +54,19 @@ class bistate_aggregator extends \local_treestudyplan\aggregator {
return $this->agcfg;
}
/**
* Create new instance of aggregation method
* @param string $configstr Aggregation configuration string
*/
public function __construct($configstr) {
// Allow public constructor for testing purposes.
$this->initialize($configstr);
}
/**
* Initialize the aggregation method
* @param string $configstr Aggregation configuration string
*/
protected function initialize($configstr) {
// First initialize with the defaults.
@ -86,7 +101,10 @@ class bistate_aggregator extends \local_treestudyplan\aggregator {
}
}
// Return active configuration model.
/**
* Return the current configuration string.
* @return string Configuration string
*/
public function config_string() {
return json_encode([
"thresh_excellent" => 100 * $this->cfg()->thresh_excellent,
@ -98,19 +116,43 @@ class bistate_aggregator extends \local_treestudyplan\aggregator {
]);
}
/**
* Determine if aggregation method wants to select gradables
* @return bool True if aggregation method needs gradables to be selected
*/
public function select_gradables() {
return true;
}
/**
* Determine if aggregation method is deprecated
* @return bool True if aggregation method is deprecated
*/
public function deprecated() {
return self::DEPRECATED;
}
/**
* Determine if Aggregation method makes use of "required grades" in a course/module.
* @return bool True if Aggregation method makes use of "required grades" in a course/module.
*/
public function use_required_grades() {
return true;
}
/**
* Determine if aggregation method makes use of required grades
* @return bool True if aggregation method makes use of
*/
public function use_item_conditions() {
return false;
}
/**
* Aggregate completed/failed goals into one outcome
* @param int[] $completions List of completions (completion class constants)
* @param array $required List of completions indexes that are marked as required
* @return int Aggregated completion as completion class constant
*/
public function aggregate_binary_goals(array $completions, array $required = []) {
// Function is public to allow access for the testing code.
@ -164,6 +206,20 @@ class bistate_aggregator extends \local_treestudyplan\aggregator {
}
}
/**
* Aggregate all completions in a course into one final course completion
* Possible states:
* completion::EXCELLENT - Completed with excellent results
* completion::GOOD - Completed with good results
* completion::COMPLETED - Completed
* completion::PROGRESS - Started, but not completed yey
* completion::FAILED - Failed
* completion::INCOMPLETE - Not yet started
* @param courseinfo $courseinfo Courseinfo object for the course to check
* @param studyitem $studyitem Studyitem object for the course to check
* @param int $userid Id of user to check this course for
* @return int Aggregated completion as completion class constant
*/
public function aggregate_course(courseinfo $courseinfo, studyitem $studyitem, $userid) {
$course = $courseinfo->course();
$coursefinished = ($course->enddate) ? ($course->enddate < time()) : false;
@ -190,6 +246,13 @@ class bistate_aggregator extends \local_treestudyplan\aggregator {
}
/**
* Aggregate juncton/filter inputs into one final junction outcome
* @param int[] $completion List of completion inputs
* @param studyitem $studyitem Studyitem object for the junction
* @param int $userid Id of user to check completion for
* @return int Aggregated completion as completion class constant
*/
public function aggregate_junction(array $completion, studyitem $studyitem = null, $userid = 0) {
// Aggregate multiple incoming states into one junction or finish.
// Possible states:.
@ -222,6 +285,12 @@ class bistate_aggregator extends \local_treestudyplan\aggregator {
}
}
/**
* Determine completion for a single grade and user
* @param gradeinfo $gradeinfo Gradeinfo object for grade to check
* @param mixed $userid Id of user to check completion for
* @return int Aggregated completion as completion class constant
*/
public function grade_completion(gradeinfo $gradeinfo, $userid) {
global $DB;
$table = "local_treestudyplan_gradecfg";

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Aggregate course results with moodle course completion
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -27,12 +27,20 @@ use \local_treestudyplan\corecompletioninfo;
use \local_treestudyplan\gradeinfo;
use \local_treestudyplan\studyitem;
use \local_treestudyplan\completion;
use \local_treestudyplan\debug;
/**
* Aggregate course results with moodle course completion
*/
class core_aggregator extends \local_treestudyplan\aggregator {
/** @var bool */
public const DEPRECATED = false;
/** @var array */
private $agcfg = null;
/**
* Retrieve or initialize current config object
* @return stdClass
*/
private function cfg() {
if (empty($this->agcfg)) {
$this->agcfg = (object)[
@ -42,11 +50,19 @@ class core_aggregator extends \local_treestudyplan\aggregator {
return $this->agcfg;
}
/**
* Create new instance of aggregation method
* @param string $configstr Aggregation configuration string
*/
public function __construct($configstr) {
// Allow public constructor for testing purposes.
$this->initialize($configstr);
}
/**
* Initialize the aggregation method
* @param string $configstr Aggregation configuration string
*/
protected function initialize($configstr) {
// First initialize with the defaults.
foreach (["accept_pending_as_submitted"] as $key) {
@ -66,25 +82,52 @@ class core_aggregator extends \local_treestudyplan\aggregator {
}
}
// Return active configuration model.
/**
* Return the current configuration string.
* @return string Configuration string
*/
public function config_string() {
return json_encode([
"accept_pending_as_submitted" => $this->cfg()->accept_pending_as_submitted,
]);
}
/**
* Determine if aggregation method wants to select gradables
* @return bool True if aggregation method needs gradables to be selected
*/
public function select_gradables() {
return false;
}
/**
* Determine if aggregation method is deprecated
* @return bool True if aggregation method is deprecated
*/
public function deprecated() {
return self::DEPRECATED;
}
/**
* Determine if Aggregation method makes use of "required grades" in a course/module.
* @return bool True if Aggregation method makes use of "required grades" in a course/module.
*/
public function use_required_grades() {
return true;
}
/**
* Determine if aggregation method makes use of required grades
* @return bool True if aggregation method makes use of
*/
public function use_item_conditions() {
return false;
}
/**
* Determine if the aggregation method uses core_completion, or treestudyplan custom completion.
* @return bool True if the aggregation method uses core_completion
*/
public function usecorecompletioninfo() {
return true;
}
@ -98,13 +141,11 @@ class core_aggregator extends \local_treestudyplan\aggregator {
* completion::PROGRESS - Started, but not completed yey
* completion::FAILED - Failed
* completion::INCOMPLETE - Not yet started
*
* @param mixed $courseinfo
* @param mixed $studyitem
* @param mixed $userid
* @return void
* @param courseinfo $courseinfo Courseinfo object for the course to check
* @param studyitem $studyitem Studyitem object for the course to check
* @param int $userid Id of user to check this course for
* @return int Aggregated completion as completion class constant
*/
public function aggregate_course(courseinfo $courseinfo, studyitem $studyitem, $userid) {
// Retrieve the core completion info from the core.
$course = $courseinfo->course();
@ -145,6 +186,13 @@ class core_aggregator extends \local_treestudyplan\aggregator {
}
}
/**
* Aggregate juncton/filter inputs into one final junction outcome
* @param int[] $completion List of completion inputs
* @param studyitem $studyitem Studyitem object for the junction
* @param int $userid Id of user to check completion for
* @return int Aggregated completion as completion class constant
*/
public function aggregate_junction(array $completion, studyitem $studyitem = null, $userid = 0) {
// Aggregate multiple incoming states into one junction or finish.
// Possible states:.
@ -177,10 +225,16 @@ class core_aggregator extends \local_treestudyplan\aggregator {
}
}
// CORE COMPLETION DOESN'T REALLY USE THE FUNCTIONS BELOW.
// AGGREGATORS ARE GOING TO BE DEPRECATED ANYWAY... but used in legacy parts of this plugin.
/**
* Determine completion for a single grade and user
* @param gradeinfo $gradeinfo Gradeinfo object for grade to check
* @param mixed $userid Id of user to check completion for
* @return int Aggregated completion as completion class constant
*/
public function grade_completion(gradeinfo $gradeinfo, $userid) {
// CORE COMPLETION DOESN'T REALLY USE THIS FUNCTION
global $DB;
$table = "local_treestudyplan_gradecfg";
$gradeitem = $gradeinfo->get_gradeitem();

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Aggregate course results based on failed, completed, excellent states for grades
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -27,23 +27,53 @@ use \local_treestudyplan\gradeinfo;
use \local_treestudyplan\studyitem;
use \local_treestudyplan\completion;
/**
* Aggregate course results based on failed, achieved, completed states for grades
* @deprecated This aggregation style is no longer used, but included to support old study plans
*/
class tristate_aggregator extends \local_treestudyplan\aggregator {
/** @var bool */
public const DEPRECATED = true;
/** @var string */
private const DEFAULT_CONDITION = "50";
/**
* Determine if aggregation method wants to select gradables
* @return bool True if aggregation method needs gradables to be selected
*/
public function select_gradables() {
return true;
}
/**
* Determine if aggregation method is deprecated
* @return bool True if aggregation method is deprecated
*/
public function deprecated() {
return self::DEPRECATED;
}
/**
* Determine if Aggregation method makes use of "required grades" in a course/module.
* @return bool True if Aggregation method makes use of "required grades" in a course/module.
*/
public function use_required_grades() {
return false;
}
/**
* Determine if aggregation method makes use of required grades
* @return bool True if aggregation method makes use of
*/
public function use_item_conditions() {
return true;
}
/**
* Aggregate completions into final result
* @param int[] $a List of completion inputs
* @param string $condition Condition description [ALL, 67, 50, ANY]
* @return int Aggregated completion as completion class constant
*/
protected function aggregate_completion(array $a, $condition = "50") {
if (in_array($condition, ['ALL', '67', '50', 'ANY'])) {
// Condition is one of the valid conditions.
@ -95,6 +125,20 @@ class tristate_aggregator extends \local_treestudyplan\aggregator {
}
}
/**
* Aggregate all completions in a course into one final course completion
* Possible states:
* completion::EXCELLENT - Completed with excellent results
* completion::GOOD - Completed with good results
* completion::COMPLETED - Completed
* completion::PROGRESS - Started, but not completed yey
* completion::FAILED - Failed
* completion::INCOMPLETE - Not yet started
* @param courseinfo $courseinfo Courseinfo object for the course to check
* @param studyitem $studyitem Studyitem object for the course to check
* @param int $userid Id of user to check this course for
* @return int Aggregated completion as completion class constant
*/
public function aggregate_course(courseinfo $courseinfo, studyitem $studyitem, $userid) {
$condition = $studyitem->conditions();
if (empty($condition)) {
@ -108,12 +152,25 @@ class tristate_aggregator extends \local_treestudyplan\aggregator {
return $completion;
}
/**
* Aggregate juncton/filter inputs into one final junction outcome
* @param int[] $completion List of completion inputs
* @param studyitem $studyitem Studyitem object for the junction
* @param int $userid Id of user to check completion for
* @return int Aggregated completion as completion class constant
*/
public function aggregate_junction(array $completion, studyitem $studyitem, $userid) {
$completed = self::aggregate_completion($completion, $studyitem->conditions());
// If null result (conditions are unknown/null) - default to ALL.
return isset($completed) ? $completed : (self::aggregate_completion($completion, 'ALL'));
}
/**
* Determine completion for a single grade and user
* @param gradeinfo $gradeinfo Gradeinfo object for grade to check
* @param mixed $userid Id of user to check completion for
* @return int Aggregated completion as completion class constant
*/
public function grade_completion(gradeinfo $gradeinfo, $userid) {
global $DB;
$gradeitem = $gradeinfo->get_gradeitem();

View File

@ -14,19 +14,25 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Helper functions for web services
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
namespace local_treestudyplan\local\helpers;
use \core_course_category;
defined('MOODLE_INTERNAL') || die();
require_once($CFG->dirroot.'/webservice/lib.php');
/**
* Class containing helper functions for webservices
*/
class webservicehelper {
/** @var \context_system */
private static $systemcontext = null;
/** @var \context[] */
private static $validatedcontexts = [];
/**
@ -58,10 +64,10 @@ class webservicehelper {
/**
* Test if the current user has a certain capability in any of the categories they have access to
* @param string $capability The capability to scan for in the categories
* @param \core_course_category $parent The parent category to use as a scanning base. Used internally.
* @param core_course_category $parent The parent category to use as a scanning base. Used internally.
* @return boolean
*/
public static function has_capability_in_any_category($capability, \core_course_category $parent = null) {
public static function has_capability_in_any_category($capability, core_course_category $parent = null) {
// List the categories in which the user has a specific capability.
$list = [];

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Scan submissions in assign activities
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -22,8 +22,14 @@
namespace local_treestudyplan\local\ungradedscanners;
/**
* Activity scanner for assignment activity
*/
class assign_scanner extends scanner_base {
/**
* Retrieve the ungraded submissions in this activity
*/
protected function get_ungraded_submissions() {
global $DB;
$sql = "SELECT DISTINCT asgn_sub.userid
@ -40,6 +46,9 @@ class assign_scanner extends scanner_base {
return $DB->get_fieldset_sql($sql, ['iteminstance' => $this->gi->iteminstance]);
}
/**
* Get the users with graded results
*/
protected function get_graded_users() {
global $DB;
$sql = "SELECT DISTINCT g.userid
@ -50,6 +59,11 @@ class assign_scanner extends scanner_base {
return $DB->get_fieldset_sql($sql, ['iteminstance' => $this->gi->iteminstance]);
}
/**
* Count the number of students wit ungraded submissions in this activity
* @param array $courseuserids
* @return int Number of students with ungraded submissions
*/
public function count_ungraded($courseuserids = []) {
$ungraded = $this->get_ungraded_submissions();
@ -59,6 +73,11 @@ class assign_scanner extends scanner_base {
return count($ungraded);
}
/**
* Count the number of students wit (all) graded submissions in this activity
* @param array $courseuserids
* @return int Number of students with graded submission
*/
public function count_graded($courseuserids = []) {
$ungraded = $this->get_ungraded_submissions();
$graded = $this->get_graded_users();
@ -74,6 +93,11 @@ class assign_scanner extends scanner_base {
return count($graded) - count($dual);
}
/**
* Check if specified user has ungraded submission in this activity
* @param mixed $userid User id of user to check
* @return bool If specified user has ungraded submissions in this activity
*/
public function has_ungraded_submission($userid) {
$ungraded = $this->get_ungraded_submissions();
return in_array($userid, $ungraded);

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Scan submissions in assign activities
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -25,8 +25,13 @@ namespace local_treestudyplan\local\ungradedscanners;
defined('MOODLE_INTERNAL') || die();
require_once($CFG->dirroot.'/question/engine/states.php'); // For reading question state.
/**
* Activity scanner for quiz activity
*/
class quiz_scanner extends scanner_base {
/**
* Retrieve the ungraded submissions in this activity
*/
protected function get_ungraded_submissions() {
// Count all users who have one or more questions that still need grading.
global $DB;
@ -55,6 +60,11 @@ class quiz_scanner extends scanner_base {
return array_keys($submissions);
}
/**
* Count the number of students wit ungraded submissions in this activity
* @param array $courseuserids
* @return int Number of students with ungraded submissions
*/
public function count_ungraded($courseuserids = []) {
$ungraded = $this->get_ungraded_submissions();
if (count($courseuserids) > 0) {
@ -63,6 +73,11 @@ class quiz_scanner extends scanner_base {
return count($ungraded);
}
/**
* Count the number of students wit (all) graded submissions in this activity
* @param array $courseuserids
* @return int Number of students with graded submission
*/
public function count_graded($courseuserids = []) {
// Count all users who submitted one or more finished tests.
global $DB;
@ -81,6 +96,11 @@ class quiz_scanner extends scanner_base {
return count($graded);
}
/**
* Check if specified user has ungraded submission in this activity
* @param mixed $userid User id of user to check
* @return bool If specified user has ungraded submissions in this activity
*/
public function has_ungraded_submission($userid) {
$ungraded = $this->get_ungraded_submissions();
return in_array($userid, $ungraded);

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Base class to scan submissions in activities
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -24,17 +24,40 @@ namespace local_treestudyplan\local\ungradedscanners;
use \grade_item;
/**
* Base class for activity scanners
*/
abstract class scanner_base {
/** @var grade_item */
protected $gi;
/**
* Create new object based on grade_item
* @param grade_item $gi The grade item for this activity
*/
public function __construct(grade_item $gi) {
$this->gi = $gi;
}
/**
* Count the number of students wit ungraded submissions in this activity
* @param array $courseuserids
* @return int Number of students with ungraded submissions
*/
abstract public function count_ungraded($courseuserids = []);
/**
* Count the number of students wit (all) graded submissions in this activity
* @param array $courseuserids
* @return int Number of students with graded submission
*/
abstract public function count_graded($courseuserids = []);
/**
* Check if specified user has ungraded submission in this activity
* @param mixed $userid User id of user to check
* @return bool If specified user has ungraded submissions in this activity
*/
abstract public function has_ungraded_submission($userid);
}

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Privacy information metadata
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -22,17 +22,21 @@
namespace local_treestudyplan\privacy;
use core_privacy\local\metadata\collection;
use \core_privacy\local\metadata\collection;
use \core_privacy\local\request\userlist;
use core_privacy\local\request\contextlist;
use \core_privacy\local\request\contextlist;
use \core_privacy\local\request\approved_contextlist;
use \core_privacy\local\request\approved_userlist;
use \core_privacy\local\request\deletion_criteria;
use \core_privacy\local\request\writer;
use \core_privacy\local\request\helper;
use \core_privacy\local\request\transform;
use tool_dataprivacy\context_instance;
use \tool_dataprivacy\context_instance;
use \context;
/**
* Privacy provider
*/
class provider implements \core_privacy\local\metadata\provider,
\core_privacy\local\request\plugin\provider,
\core_privacy\local\request\core_userlist_provider {
@ -46,6 +50,11 @@ class provider implements \core_privacy\local\metadata\provider,
return 'privacy:metadata';
}
/**
* Get metadata about collected personal data
* @param collection $collection
* @return collection
*/
public static function get_metadata(collection $collection): collection {
$collection->add_database_table(
@ -71,7 +80,6 @@ class provider implements \core_privacy\local\metadata\provider,
/**
* Get the list of contexts that contain user information for the specified user.
*
* @param int $userid The user to search.
* @return contextlist $contextlist The contextlist containing the list of contexts used in this plugin.
*/
@ -91,7 +99,6 @@ class provider implements \core_privacy\local\metadata\provider,
/**
* Export all user data for the specified user, in the specified contexts.
*
* @param approved_contextlist $contextlist The approved contexts to export information for.
*/
public static function export_user_data(approved_contextlist $contextlist) {
@ -134,8 +141,7 @@ class provider implements \core_privacy\local\metadata\provider,
/**
* Export the supplied personal data for an invitation.
*
* @param $invit The invitation record.
* @param stdClass $invit The invitation record.
*/
protected static function export_invitation_data_for_user($invit) {
$context = \context_system::instance();
@ -147,9 +153,8 @@ class provider implements \core_privacy\local\metadata\provider,
}
/**
* Export the supplied personal data for an invitation.
*
* @param $invit The invitation record.
* Export studyplan data for (current) user
* @param stdClass $studyplan The studyplan
*/
protected static function export_studyplan_data_for_user($studyplan) {
$context = \context_system::instance();
@ -163,10 +168,9 @@ class provider implements \core_privacy\local\metadata\provider,
/**
* Delete all data for all users in the specified context.
* Used when a context is past it's data retention period
*
* @param context $context The specific context to delete data for.
*/
public static function delete_data_for_all_users_in_context(\context $context) {
public static function delete_data_for_all_users_in_context(context $context) {
global $DB;
// Find studyplans in context.
if ($context->contextlevel == CONTEXT_COURSECAT) {
@ -218,7 +222,6 @@ class provider implements \core_privacy\local\metadata\provider,
/**
* Get the list of users who have data within a context.
*
* @param userlist $userlist The userlist containing the list of users who have data in this context/plugin combination.
*/
public static function get_users_in_context(userlist $userlist) {
@ -250,7 +253,6 @@ class provider implements \core_privacy\local\metadata\provider,
/**
* Delete multiple users within a single context.
*
* @param approved_userlist $userlist The approved context and user information to delete information for.
*/
public static function delete_data_for_users(approved_userlist $userlist) {

View File

@ -54,7 +54,7 @@ class studyplan {
$this->id = $id;
$this->r = $DB->get_record(self::TABLE, ['id' => $id]);
$this->aggregator = aggregator::createordefault($this->r->aggregation, $this->r->aggregation_config);
$this->aggregator = aggregator::create_or_default($this->r->aggregation, $this->r->aggregation_config);
}
public function id() {
@ -250,7 +250,7 @@ class studyplan {
$this->context = null;
$this->context();
// Reload aggregator.
$this->aggregator = aggregator::createordefault($this->r->aggregation, $this->r->aggregation_config);
$this->aggregator = aggregator::create_or_default($this->r->aggregation, $this->r->aggregation_config);
// Start temporary skräpp code.
// TODO: Until proper page editing is implemented, copy data from studyplan to it's first page.

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Webservice return value to describe a single event as successful or not
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -22,23 +22,54 @@
namespace local_treestudyplan;
/**
* Describes a webservice result a successful or not with optional message
*/
class success {
/**
* Success (true) or failed (false)
* @var bool
*/
private $success;
/**
* Messsage passed with result
* @var string
*/
private $msg;
/**
* Create new successful result with optional message
* @param string $msg Message to add to result
* @return self Succesful success object
*/
public static function success($msg = "") {
return new self(true, $msg);
}
/**
* Create new failed result with optional message
* @param string $msg Message to add to result
* @return self Failed success object
*/
public static function fail($msg = "") {
return new self(false, $msg);
}
/**
* Create new succes result
* @param bool $success Whether result is succesful or not
* @param string $msg Message to add to result
*/
public function __construct($success, $msg) {
$this->success = ($success) ? true : false;
$this->msg = $msg;
}
/**
* Describe the result for the
* @return external_single_structure
*/
public static function structure() {
return new \external_single_structure([
"success" => new \external_value(PARAM_BOOL, 'operation completed succesfully'),
@ -46,14 +77,30 @@ class success {
]);
}
/**
* Make the webservice result model
*
* @return array Webservice value
*/
public function model() {
return ["success" => $this->success, "msg" => $this->msg];
}
/**
* Get success status of object
*
* @return bool If this success is successful or not
*/
public function successful() {
return $this->success;
}
/**
* Get message
*
* @return string Message
*/
public function msg() {
return $this->msg;
}

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Task to autosync studyplan associated cohorts and users with the courses in the studyplan
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -28,6 +28,9 @@ use local_treestudyplan\studyplan;
use local_treestudyplan\cascadecohortsync;
use local_treestudyplan\cascadeusersync;
/**
* Task to enrol users and cohorts associated with a studyplan in all courses linked in that studyplan
*/
class autocohortsync extends \core\task\scheduled_task {
/**

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Background task to refresh the list of associaded teachers with studyplans
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -26,7 +26,14 @@ defined('MOODLE_INTERNAL') || die();
require_once($CFG->dirroot.'/course/externallib.php');
use local_treestudyplan\teachingfinder;
/**
* Background task to refresh the list of associaded teachers with studyplans
*/
class refreshteacherlist extends \core\task\scheduled_task {
/**
* Maximum time a result is valid before refreshing
* @var int
*/
const CACHE_TIME = 4 * 60 * 60; // 2 hours.
/**

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Developer CLI tool. Primes grade generator with random student properties
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Developer CLI tool. Fill all the gradables in a study plan with random values
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Describes roles and permissions
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Webservice function register
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Background task register
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

View File

@ -14,12 +14,18 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Database upgrade script
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
/**
* Hook to upgrade database upon plugin upgrade
* @param mixed $oldversion Version of plugin database before upgrade
* @return bool Upgrade success status
*
*/
function xmldb_local_treestudyplan_upgrade($oldversion) {
global $DB;
$dbman = $DB->get_manager();

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Documentation renderer
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Edit an existing or new invitation to view a studyplan
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Edit/manage study plans
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -80,7 +80,14 @@ $PAGE->requires->js_call_amd('local_treestudyplan/page-edit-plan', 'init', [$stu
$catlist = courseservice::list_accessible_categories_with_usage("edit");
// Local translate function.
/**
* Shortcut function to provide translations
*
* @param mixed $str Translation key
* @param null|string[] $param Parameters to pass to translation
* @param string $plugin Location to search for translation strings
* @return string Translation of key
*/
function t($str, $param = null, $plugin = 'local_treestudyplan') {
print get_string($str, $plugin, $param);
}

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Entry point for students to manage invitations to view their study plan
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Entry point for external people to access a studyplan view with an invitation
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -23,7 +23,14 @@
require_once("../../config.php");
// Since this page is externally accessed and validated in a different way, no login is needed.
// Local translate function.
/**
* Shortcut function to provide translations
*
* @param mixed $str Translation key
* @param null|string[] $param Parameters to pass to translation
* @param string $plugin Location to search for translation strings
* @return string Translation of key
*/
function t($str, $param = null, $plugin = 'local_treestudyplan') {
print get_string($str, $plugin, $param);
}

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* English language file
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Dutch language file
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

67
lib.php
View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Moodle hook functions and some internally used functions
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -26,7 +26,12 @@
use local_treestudyplan\local\helpers\webservicehelper;
use \local_treestudyplan\studyplan;
function local_treestudyplan_unit_get_editor_options($context) {
/**
* Describe editor options
* @param context $context Context for options
* @return array Editor options
*/
function local_treestudyplan_unit_get_editor_options(context $context) {
global $CFG;
return ['subdirs' => 1,
'maxbytes' => $CFG->maxbytes,
@ -37,6 +42,10 @@ function local_treestudyplan_unit_get_editor_options($context) {
'trusttext' => 0];
}
/**
* Hook to extend navigation
* @param global_navigation $navigation Navigation object
*/
function local_treestudyplan_extend_navigation(global_navigation $navigation) {
global $CFG, $PAGE, $COURSE, $USER;
@ -148,6 +157,11 @@ function local_treestudyplan_extend_navigation(global_navigation $navigation) {
}
/**
* Hook to extend navigation in category view
* @param mixed $navigation
* @param context_coursecat $coursecategorycontext
*/
function local_treestudyplan_extend_navigation_category_settings($navigation, context_coursecat $coursecategorycontext) {
global $CFG, $PAGE;
$categoryid = $coursecategorycontext->instanceid;
@ -176,6 +190,11 @@ function local_treestudyplan_extend_navigation_category_settings($navigation, co
}
/**
* Map fontawesome icons for use in flat navigation
* @return array Icon mapping
*
*/
function local_treestudyplan_get_fontawesome_icon_map() {
// Create the icon map with the icons which are used in any case.
@ -184,9 +203,9 @@ function local_treestudyplan_get_fontawesome_icon_map() {
'local_treestudyplan:editplans' => 'fa-share-alt',
'local_treestudyplan:viewplans' => 'fa-share-alt',
];
return $iconmapping;
}
/**
* Helper function to reset the icon system used as updatecallback function when saving some of the plugin's settings.
*/
@ -201,6 +220,11 @@ function local_treestudyplan_reset_fontawesome_icon_map() {
$instance->get_icon_name_map();
}
/**
* Send invitation to invited person
* @param mixed $inviteid Database id of the invitation
*
*/
function local_treestudyplan_send_invite($inviteid) {
global $DB, $USER, $CFG;
$invite = $DB->get_record("local_treestudyplan_invit", array('id' => $inviteid));
@ -259,38 +283,11 @@ function local_treestudyplan_send_invite($inviteid) {
}
function local_treestudyplan_find_cohortmembers($cohortid) {
global $DB;
// By default wherecondition retrieves all users except the deleted, not confirmed and guest.
$params = ['cohortid' => $cohortid];
$sql = "SELECT * FROM {user} u
JOIN {cohort_members} cm ON (cm.userid = u.id AND cm.cohortid = :cohortid)
WHERE u.suspended = 0 AND u.id > 1
ORDER BY u.lastname
";
$availableusers = $DB->get_records_sql($sql, $params);
return $availableusers;
}
function local_treestudyplan_get_cohort_path($cohort) {
$cohortcontext = context::instance_by_id($cohort->contextid);
if ($cohortcontext && $cohortcontext->id != SYSCONTEXTID) {
$ctxpath = array_map(
function($ctx) {
return $ctx->get_context_name(false);
},
$cohortcontext->get_parent_contexts(true)
);
array_pop($ctxpath); // Pop system context off the list.
$ctxpath = array_reverse($ctxpath);
$ctxpath[] = $cohort->name;
return implode(" / ", $ctxpath);
} else {
return $cohort->name;
}
}
/**
* Hook to display fragment of activity/mod settings editor. Used in feature to edit name and description of activity
* @param mixed $args
* @return string Rendered form output HTML
*/
function local_treestudyplan_output_fragment_mod_edit_form($args) {
global $CFG;
global $DB;

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Entry point for other moodle modules to embed the user's report in a view
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -41,7 +41,15 @@ $PAGE->requires->css(new moodle_url($CFG->wwwroot.'/local/treestudyplan/css/boot
$PAGE->requires->css(new moodle_url($CFG->wwwroot.'/local/treestudyplan/css/devstyles.css'));
$PAGE->requires->js_call_amd('local_treestudyplan/page-myreport', 'init');
// Local translate function.
/**
* Shortcut function to provide translations
*
* @param mixed $str Translation key
* @param null|string[] $param Parameters to pass to translation
* @param string $plugin Location to search for translation strings
* @return string Translation of key
*/
function t($str, $param = null, $plugin = 'local_treestudyplan') {
print get_string($str, $plugin, $param);
}

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Show student's studyplans in a report overview
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -49,7 +49,14 @@ $PAGE->requires->css(new moodle_url($CFG->wwwroot.'/local/treestudyplan/css/boot
$PAGE->requires->css(new moodle_url($CFG->wwwroot.'/local/treestudyplan/css/devstyles.css'));
$PAGE->requires->js_call_amd('local_treestudyplan/page-myreport', 'init', [$teachermode ? 'teaching' : 'myreport']);
// Local translate function.
/**
* Shortcut function to provide translations
*
* @param mixed $str Translation key
* @param null|string[] $param Parameters to pass to translation
* @param string $plugin Location to search for translation strings
* @return string Translation of key
*/
function t($str, $param = null, $plugin = 'local_treestudyplan') {
print get_string($str, $plugin, $param);
}

View File

@ -15,11 +15,11 @@
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
* Local plugin "Boost navigation fumbling" - Settings
* Local plugin Settings
*
* @package local_chronotable
* @copyright 2017 Alexander Bias, Ulm University <alexander.bias@uni-ulm.de>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later.
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
defined('MOODLE_INTERNAL') || die();

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Plugin version
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* View study plans - teacher view and student view
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -78,7 +78,14 @@ $PAGE->requires->css(new moodle_url($CFG->wwwroot.'/local/treestudyplan/css/boot
$PAGE->requires->css(new moodle_url($CFG->wwwroot.'/local/treestudyplan/css/devstyles.css'));
$PAGE->requires->js_call_amd('local_treestudyplan/page-view-plan', 'init', [$studyplancontext->id, $categoryid]);
// Local translate function.
/**
* Shortcut function to provide translations
*
* @param mixed $str Translation key
* @param null|string[] $param Parameters to pass to translation
* @param string $plugin Location to search for translation strings
* @return string Translation of key
*/
function t($str, $param = null, $plugin = 'local_treestudyplan') {
print get_string($str, $plugin, $param);
}