Miqra-Engineering/moodle_local_treestudyplan
2
0
Fork 0
Code Issues 13 Pull Requests Packages Projects Releases 4 Wiki Activity

PHPDoc documentation

Browse Source
This commit is contained in:
PMKuipers 2023-08-27 22:20:17 +02:00
parent 77c13e2847
commit 92536683f0
27 changed files with 230 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
classes/aggregator.php
View File

@ -32,7 +32,7 @@ require_once($CFG->libdir.'/externallib.php');
*/
abstract class aggregator {
/** Fallback aggregator if method not found
* @var string
* @var string
* */
private const FALLBACK = "core";
/** @var string[] */
@ -71,7 +71,7 @@ abstract class aggregator {
];
}
/**
* Create a new aggregatior object based on the specified method
* @param mixed $method Aggregation method
@ -89,7 +89,7 @@ abstract class aggregator {
}
/**
* Create a new aggregatior object based on the specified method,
* 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
@ -170,7 +170,7 @@ abstract class aggregator {
/**
* Determine if aggregation method makes use of required grades
* @return bool True if aggregation method makes use of
* @return bool True if aggregation method makes use of
*/
abstract public function use_item_conditions();
@ -185,12 +185,12 @@ abstract class aggregator {
/**
* 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

4
classes/badgeinfo.php
View File

@ -48,6 +48,10 @@ class badgeinfo {
$this->badge = $badge;
}
/**
* Return full name
* @return string
*/
public function name() {
return $this->badge->name;
}

2
classes/cascadeusersync.php
View File

@ -47,7 +47,7 @@ class cascadeusersync {
$this->studyplan = $studyplan;
}
/**
* Enroll all users associated to the studyplan in the courses linked to this studyplan
*/

2
classes/corecompletioninfo.php
View File

@ -44,7 +44,7 @@ class corecompletioninfo {
/** @var \course_modinfo */
private $modinfo;
/**
/**
* Cached dict of completion:: constants to equivalent webservice strings
* @var array */
private static $completionhandles = null;

99
classes/courseinfo.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/>.
/**
*
* Class to process information about a course
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -33,36 +33,70 @@ use \grade_item;
use \grade_scale;
use \grade_outcome;
/**
* Class to process information about a course
*/
class courseinfo {
/** @var string */
/**
* Table name used in this class
* @var string */
const TABLE = 'course';
/** @var stdClass */
private $course;
/** @var \context */
private $context;
/** @var \context */
private $coursecontext;
/** @var studyitem */
private $studyitem;
/** @var array */
private static $contentitems = null;
/**
* Return database identifier
* @return int
*/
public function id() {
return $this->course->id;
}
/**
* Return short name
* @return string
*/
public function shortname() {
return $this->course->shortname;
}
/**
* Return course record
* @return stdClass
*/
public function course() {
return $this->course; // Php arrays are assigned by copy.
return $this->course;
}
/**
* Return course context
* @return \context
*/
public function course_context() {
return $this->coursecontext;
}
/**
* Return course's category context
* @return \context
*/
public function category_context() {
return $this->context;
}
/**
* Get content items (activity icons) from the repository
* @return content_item[]
*/
protected function get_contentitems() {
global $PAGE;
if (empty(static::$contentitems)) {
@ -72,11 +106,19 @@ class courseinfo {
return static::$contentitems;
}
protected function am_teacher() {
/**
* Check if current user is teacher in this course
* @return book
*/
protected function am_teacher() : bool {
global $USER;
return is_enrolled($this->coursecontext, $USER, 'mod/assign:grade');
}
/**
* Check if specified user can select gradables in this course
* @param int $userid User id to check for . Leave empty to check current user
*/
protected function i_can_select_gradables($userid = -1) {
global $USER, $DB;
if ($userid <= 0) {
@ -87,6 +129,11 @@ class courseinfo {
return($usr && is_enrolled($this->coursecontext, $usr, 'local/treestudyplan:selectowngradables'));
}
/**
* Get specific contentitem (activity icons) by name
* @param mixed $name Name of content item
* @return content_item|null
*/
public static function get_contentitem($name) {
$contentitems = static::get_contentitems();
for ($i = 0; $i < count($contentitems); $i++) {
@ -97,6 +144,11 @@ class courseinfo {
return null;
}
/**
* Construct courseinfo based on course id and
* @param int $id Course id
* @param studyitem|null $studyitem Studyitem linking this course (if applicable)
*/
public function __construct($id, studyitem $studyitem = null) {
global $DB;
$this->studyitem = $studyitem;
@ -105,17 +157,32 @@ class courseinfo {
$this->coursecontext = \context_course::instance($this->course->id);
}
/**
* Check if a course with the given ID exists
* @param int $id Course id
* @return bool
*/
public static function exists($id) {
global $DB;
return is_numeric($id) && $DB->record_exists(self::TABLE, ['id' => $id]);
}
/**
* Find course id from shortname
* @param string $shortname Shortname of the course
* @return int Course id
*/
public static function id_from_shortname($shortname) {
global $DB;
return $DB->get_field(self::TABLE, "id", ['shortname' => $shortname]);
}
/**
* Determine course timing [future, present or past] based on a course date
* @param stdClass $course Course database record
* @return string 'future', 'present' or 'past'
*/
public static function coursetiming($course) {
$now = time();
if ($now > $course->startdate) {
@ -129,10 +196,18 @@ class courseinfo {
}
}
/**
* Determine course timing for this course [future, present or past]
* @return string 'future', 'present' or 'past'
*/
public function timing() {
return self::coursetiming($this->course);
}
/**
* Determine proper display name for this course based on config settings, custom fields etc...
* @return string Display name for the course
*/
public function displayname() {
$displayfield = get_config("local_treestudyplan", "display_field");
if ($displayfield == "idnumber") {
@ -158,6 +233,11 @@ class courseinfo {
return $this->course->shortname;
}
/**
* Webservice structure for basic info
* @param int $value Webservice requirement constant
* @return external_single_structure Webservice output structure
*/
public static function simple_structure($value = VALUE_REQUIRED) {
return new \external_single_structure([
"id" => new \external_value(PARAM_INT, 'linked course id'),
@ -168,6 +248,10 @@ class courseinfo {
], 'referenced course information', $value);
}
/**
* Webservice model for basic info
* @return array Webservice data model
*/
public function simple_model() {
$contextinfo = new contextinfo($this->context);
$info = [
@ -209,6 +293,8 @@ class courseinfo {
/**
* Webservice model for editor info
* @param studyitem $studyitem Specify a specific study item to check gradable selections for. Leave empty to use default
* @param bool $usecorecompletioninfo Whether to use corecompletion info instead of custom selected gradables
* @return array Webservice data model
*/
public function editor_model(studyitem $studyitem = null, $usecorecompletioninfo = false) {
@ -235,10 +321,10 @@ class courseinfo {
];
if (!$usecorecompletioninfo) {
$gradables = gradeinfo::list_course_gradables($this->course, $studyitem);
$gradables = gradeinfo::list_course_gradables($this->course, $studyitem ? $studyitem : $this->studyitem );
foreach ($gradables as $gradable) {
$info['grades'][] = $gradable->editor_model($studyitem);
$info['grades'][] = $gradable->editor_model($studyitem ? $studyitem : $this->studyitem);
}
} else {
$cc = new corecompletioninfo($this->course);
@ -272,6 +358,7 @@ class courseinfo {
/**
* Webservice model for user info
* @param int $userid ID of user to check specific info for
* @param bool $usecorecompletioninfo Whether to use corecompletion info instead of custom selected gradables
* @return array Webservice data model
*/
public function user_model($userid, $usecorecompletioninfo = false) {

8
classes/courseservice.php
View File

@ -381,9 +381,9 @@ class courseservice extends \external_api {
}
/**************************************
*
*
* Progress scanners for teacherview
*
*
**************************************/
/**
@ -408,7 +408,7 @@ class courseservice extends \external_api {
/**
* Scan grade item for progress statistics
* @param mixed $gradeitemid Grade item id
* @param mixed $gradeitemid Grade item id
* @param mixed $studyplanid Id of studyitem the grade is selected in
* @return array
*/
@ -499,7 +499,7 @@ class courseservice extends \external_api {
}
/**
* Scan badge for completion progress statistica
* Scan badge for completion progress statistica
* @param mixed $badgeid ID of the badge
* @param mixed $studyplanid ID of the relevant study plan
* @return array

16
classes/gradeinfo.php
View File

@ -93,7 +93,7 @@ class gradeinfo {
/**
* Get the grade_item
* @return grade_item
* @return grade_item
*/
public function get_gradeitem() : grade_item {
return $this->gradeitem;
@ -102,7 +102,7 @@ class gradeinfo {
* Get the gradingscanner
* @return gradingscanner
*/
public function get_gradingscanner() : gradingscanner{
public function get_gradingscanner() : gradingscanner {
return $this->gradingscanner;
}
@ -110,7 +110,7 @@ class gradeinfo {
* Get the grade's scale if applicable
* @return grade_scale|null
*/
public function get_scale() : ?grade_scale{
public function get_scale() : ?grade_scale {
return $this->scale;
}
@ -157,7 +157,7 @@ class gradeinfo {
}
/**
* Create new object around a grade_item
* Create new object around a grade_item
* @param int $id Grade item id of the grade item to use as base
* @param studyitem|null $studyitem Studyitem containg the course that references this grade
*/
@ -332,7 +332,7 @@ class gradeinfo {
/**
* Webservice model for user info
* @param int $userid ID of user to check specific info for
* @param int $userid ID of user to check specific info for
* @return array Webservice data model
*/
public function user_model($userid) {
@ -468,7 +468,7 @@ class gradeinfo {
* @param studyitem $studyitem The studyitem to search for
* @return self[] Array of gradeinfo
*/
public static function list_studyitem_gradables(studyitem $studyitem) : array{
public static function list_studyitem_gradables(studyitem $studyitem) : array {
global $DB;
$table = 'local_treestudyplan_gradeinc';
$list = [];
@ -494,7 +494,7 @@ class gradeinfo {
return $list;
}
/**
* Webservice executor to include grade with studyitem or not.
* if both $inclue and $required are false, any existing DB record will be removed
@ -502,7 +502,7 @@ class gradeinfo {
* @param int $itemid ID of the study item
* @param bool $include Select grade_item for studyitem or not
* @param bool $required Mark grade_item as required or not
* @return success Always returns successful success object
* @return success Always returns successful success object
*/
public static function include_grade(int $gradeid, int $itemid, bool $include, bool $required = false) {
global $DB;

4
classes/local/aggregators/bistate_aggregator.php
View File

@ -104,7 +104,7 @@ class bistate_aggregator extends \local_treestudyplan\aggregator {
/**
* Return the current configuration string.
* @return string Configuration string
*/
*/
public function config_string() {
return json_encode([
"thresh_excellent" => 100 * $this->cfg()->thresh_excellent,
@ -141,7 +141,7 @@ class bistate_aggregator extends \local_treestudyplan\aggregator {
/**
* Determine if aggregation method makes use of required grades
* @return bool True if aggregation method makes use of
* @return bool True if aggregation method makes use of
*/
public function use_item_conditions() {
return false;

10
classes/local/aggregators/core_aggregator.php
View File

@ -85,7 +85,7 @@ class core_aggregator extends \local_treestudyplan\aggregator {
/**
* 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,
@ -118,7 +118,7 @@ class core_aggregator extends \local_treestudyplan\aggregator {
/**
* Determine if aggregation method makes use of required grades
* @return bool True if aggregation method makes use of
* @return bool True if aggregation method makes use of
*/
public function use_item_conditions() {
return false;
@ -225,7 +225,7 @@ class core_aggregator extends \local_treestudyplan\aggregator {
}
}
/**
* Determine completion for a single grade and user
* @param gradeinfo $gradeinfo Gradeinfo object for grade to check
@ -233,8 +233,8 @@ class core_aggregator extends \local_treestudyplan\aggregator {
* @return int Aggregated completion as completion class constant
*/
public function grade_completion(gradeinfo $gradeinfo, $userid) {
// CORE COMPLETION DOESN'T REALLY USE THIS FUNCTION
// CORE COMPLETION DOESN'T REALLY USE THIS FUNCTION.
global $DB;
$table = "local_treestudyplan_gradecfg";
$gradeitem = $gradeinfo->get_gradeitem();

2
classes/local/aggregators/tristate_aggregator.php
View File

@ -62,7 +62,7 @@ class tristate_aggregator extends \local_treestudyplan\aggregator {
/**
* Determine if aggregation method makes use of required grades
* @return bool True if aggregation method makes use of
* @return bool True if aggregation method makes use of
*/
public function use_item_conditions() {
return true;

8
classes/local/gradegenerator.php
View File

@ -117,7 +117,7 @@ class gradegenerator {
}
/**
/**
* Register a new student in the skill table
* @param string $student Student identifier
*/
@ -132,7 +132,7 @@ class gradegenerator {
}
/**
* Add a specific skill for a student
* Add a specific skill for a student
* @param string $student Student identifier
* @param string $skill Skill identifier
*/
@ -160,7 +160,7 @@ class gradegenerator {
$this->table[$student]["lastname"] = $lastname;
}
/**
/**
* Generate a number of random results for a given student and skill
* @param string $student Student identifier
* @param string $skill Skill identifier
@ -206,7 +206,7 @@ class gradegenerator {
}
/**
* Generate results for a number of gradeinfo
* Generate results for a number of gradeinfo
* Returns (object)[ "gi" => <gradeinfo object>,
* "grade" => <randomized grade>
* "fb" => <randomized feedback>

2
classes/local/ungradedscanners/assign_scanner.php
View File

@ -59,7 +59,7 @@ 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

14
classes/period.php
View File

@ -32,7 +32,7 @@ class period {
private static $pagecache = [];
/**
* Holds database record
* Holds database record
* @var stdClass
*/
private $r; // Holds database record.
@ -130,6 +130,10 @@ class period {
$this->page = studyplanpage::find_by_id($this->r->page_id);
}
/**
* Return database identifier
* @return int
*/
public function id() {
return $this->id;
}
@ -142,10 +146,18 @@ class period {
return $this->page;
}
/**
* Return short name
* @return string
*/
public function shortname() {
return $this->r->shortname;
}
/**
* Return full name
* @return string
*/
public function fullname() {
return $this->r->fullname;
}

6
classes/reportinvite_form.php
View File

@ -26,7 +26,7 @@ require_once("$CFG->libdir/formslib.php");
require_once("$CFG->dirroot/local/treestudyplan/lib.php");
/**
* Form to edit invitations to view the user's studyplans
* Form to edit invitations to view the user's studyplans
*/
class reportinvite_form extends moodleform {
// Add elements to form.
@ -60,8 +60,8 @@ class reportinvite_form extends moodleform {
$this->add_action_buttons();
}
/**
/**
* Custom validation should be added here.
* @param array $data Supplied user data
* @param array $files Any uploaded files

11
classes/studyitem.php
View File

@ -39,7 +39,7 @@ class studyitem {
private static $studyitemcache = [];
/**
* Holds database record
* Holds database record
* @var stdClass
*/
private $r; // Holds database record.
@ -52,6 +52,11 @@ class studyitem {
/** @var aggragator */
private $aggregator;
/**
* Return the context the studyplan is associated to
* @return \context
*/
public function context(): \context {
return $this->studyline->context();
}
@ -80,6 +85,10 @@ class studyitem {
$this->aggregator = $this->studyline()->studyplan()->aggregator();
}
/**
* Return database identifier
* @return int
*/
public function id() {
return $this->id;
}

4
classes/studyitemconnection.php
View File

@ -31,12 +31,12 @@ require_once($CFG->libdir.'/externallib.php');
class studyitemconnection {
/**
* Database table for this model
* Database table for this model
* @var string */
const TABLE = "local_treestudyplan_connect";
/**
* Holds database record
* Holds database record
* @var stdClass
*/
private $r;

15
classes/studyline.php
View File

@ -48,7 +48,7 @@ class studyline {
private static $studylinecache = [];
/**
* Holds database record
* Holds database record
* @var stdClass
*/
private $r; // Holds database record.
@ -59,6 +59,11 @@ class studyline {
/** @var studyplan*/
private $studyplan;
/**
* Return the context the studyplan is associated to
* @return \context
*/
public function context(): \context {
return $this->studyplan->context();
}
@ -86,10 +91,18 @@ class studyline {
$this->studyplan = $this->page->studyplan();
}
/**
* Return database identifier
* @return int
*/
public function id() {
return $this->id;
}
/**
* Return full name
* @return string
*/
public function name() {
return $this->r->name;
}

28
classes/studyplan.php
View File

@ -32,7 +32,7 @@ class studyplan {
private static $studyplancache = [];
/**
* Holds database record
* Holds database record
* @var stdClass
*/
private $r; // Holds database record.
@ -65,14 +65,26 @@ class studyplan {
$this->aggregator = aggregator::create_or_default($this->r->aggregation, $this->r->aggregation_config);
}
/**
* Return database identifier
* @return int
*/
public function id() {
return $this->id;
}
/**
* Return short name
* @return string
*/
public function shortname() {
return $this->r->shortname;
}
/**
* Return full name
* @return string
*/
public function name() {
return $this->r->name;
}
@ -88,7 +100,8 @@ class studyplan {
}
/**
* Return the context this studyplan is associated to
* Return the context the studyplan is associated to
* @return \context
*/
public function context(): \context {
if (!isset($this->context)) {
@ -103,6 +116,11 @@ class studyplan {
return $this->context;
}
/**
* Webservice structure for basic info
* @param int $value Webservice requirement constant
* @return external_single_structure Webservice output structure
*/
public static function simple_structure($value = VALUE_REQUIRED) {
return new \external_single_structure([
"id" => new \external_value(PARAM_INT, 'id of studyplan'),
@ -118,6 +136,10 @@ class studyplan {
], 'Basic studyplan info', $value);
}
/**
* Webservice model for basic info
* @return array Webservice data model
*/
public function simple_model() {
$pages = [];
foreach ($this->pages() as $p) {
@ -559,7 +581,7 @@ class studyplan {
}
/**
* Export all pages
* Export all pages
* @return array information model
*/
public function export_pages_model() {

23
classes/studyplanpage.php
View File

@ -32,7 +32,7 @@ class studyplanpage {
private static $cache = [];
/**
* Holds database record
* Holds database record
* @var stdClass
*/
private $r; // Holds database record.
@ -60,6 +60,10 @@ class studyplanpage {
$this->studyplan = studyplan::find_by_id($this->r->studyplan_id);
}
/**
* Return database identifier
* @return int
*/
public function id() {
return $this->id;
}
@ -68,6 +72,10 @@ class studyplanpage {
return $this->studyplan;
}
/**
* Return short name
* @return string
*/
public function shortname() {
return $this->r->shortname;
}
@ -76,6 +84,10 @@ class studyplanpage {
return $this->r->periods;
}
/**
* Return full name
* @return string
*/
public function fullname() {
return $this->r->fullname;
}
@ -94,6 +106,11 @@ class studyplanpage {
}
/**
* Webservice structure for basic info
* @param int $value Webservice requirement constant
* @return external_single_structure Webservice output structure
*/
public static function simple_structure($value = VALUE_REQUIRED) {
return new \external_single_structure([
"id" => new \external_value(PARAM_INT, 'id of studyplan page'),
@ -107,6 +124,10 @@ class studyplanpage {
], 'Studyplan page basic info', $value);
}
/**
* Webservice model for basic info
* @return array Webservice data model
*/
public function simple_model() {
return [
'id' => $this->r->id,

4
classes/success.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/>.
/**
* Webservice return value to describe a single event as successful or not
* 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
@ -68,7 +68,7 @@ class success {
/**
* Describe the result for the webservice model
* @return external_single_structure
* @return external_single_structure
*/
public static function structure() {
return new \external_single_structure([

2
classes/task/autocohortsync.php
View File

@ -29,7 +29,7 @@ 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
* Task to enrol users and cohorts associated with a studyplan in all courses linked in that studyplan
*/
class autocohortsync extends \core\task\scheduled_task {

2
classes/task/refreshteacherlist.php
View File

@ -27,7 +27,7 @@ require_once($CFG->dirroot.'/course/externallib.php');
use local_treestudyplan\teachingfinder;
/**
* Background task to refresh the list of associaded teachers with studyplans
* Background task to refresh the list of associaded teachers with studyplans
*/
class refreshteacherlist extends \core\task\scheduled_task {
/**

2
classes/teachingfinder.php
View File

@ -26,7 +26,7 @@ namespace local_treestudyplan;
* Class to find and cache which studyplans a teacher is teaching courses in
*/
class teachingfinder {
/**
/**
* Table name used for caching teacher info
* @var string
*/

2
cli/randomize_grades.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/>.
/**
* Developer CLI tool. Fill all the gradables in a study plan with random values
* 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

2
db/upgrade.php
View File

@ -24,7 +24,7 @@
* 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;

8
lib.php
View File

@ -192,8 +192,8 @@ function local_treestudyplan_extend_navigation_category_settings($navigation, co
/**
* Map fontawesome icons for use in flat navigation
* @return array Icon mapping
*
* @return array Icon mapping
*
*/
function local_treestudyplan_get_fontawesome_icon_map() {
@ -223,7 +223,7 @@ function local_treestudyplan_reset_fontawesome_icon_map() {
/**
* Send invitation to invited person
* @param mixed $inviteid Database id of the invitation
*
*
*/
function local_treestudyplan_send_invite($inviteid) {
global $DB, $USER, $CFG;
@ -285,7 +285,7 @@ function local_treestudyplan_send_invite($inviteid) {
/**
* Hook to display fragment of activity/mod settings editor. Used in feature to edit name and description of activity
* @param mixed $args
* @param mixed $args
* @return string Rendered form output HTML
*/
function local_treestudyplan_output_fragment_mod_edit_form($args) {

2
scss/readme-moodle.txt
View File

@ -16,5 +16,3 @@ production environments, the compiler will compile it into both css/devstyles.cs
and styles.css
The grunt command to compile is 'grunt scssplugin'