PHPDoc documentation

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

View File

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

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License // You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>. // along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/** /**
* * Class to process information about a course
* @package local_treestudyplan * @package local_treestudyplan
* @copyright 2023 P.M. Kuipers * @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later * @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_scale;
use \grade_outcome; use \grade_outcome;
/**
* Class to process information about a course
*/
class courseinfo { class courseinfo {
/** @var string */ /**
* Table name used in this class
* @var string */
const TABLE = 'course'; const TABLE = 'course';
/** @var stdClass */
private $course; private $course;
/** @var \context */
private $context; private $context;
/** @var \context */
private $coursecontext; private $coursecontext;
/** @var studyitem */
private $studyitem; private $studyitem;
/** @var array */
private static $contentitems = null; private static $contentitems = null;
/**
* Return database identifier
* @return int
*/
public function id() { public function id() {
return $this->course->id; return $this->course->id;
} }
/**
* Return short name
* @return string
*/
public function shortname() { public function shortname() {
return $this->course->shortname; return $this->course->shortname;
} }
/**
* Return course record
* @return stdClass
*/
public function course() { public function course() {
return $this->course; // Php arrays are assigned by copy. return $this->course;
} }
/**
* Return course context
* @return \context
*/
public function course_context() { public function course_context() {
return $this->coursecontext; return $this->coursecontext;
} }
/**
* Return course's category context
* @return \context
*/
public function category_context() { public function category_context() {
return $this->context; return $this->context;
} }
/**
* Get content items (activity icons) from the repository
* @return content_item[]
*/
protected function get_contentitems() { protected function get_contentitems() {
global $PAGE; global $PAGE;
if (empty(static::$contentitems)) { if (empty(static::$contentitems)) {
@ -72,11 +106,19 @@ class courseinfo {
return static::$contentitems; 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; global $USER;
return is_enrolled($this->coursecontext, $USER, 'mod/assign:grade'); 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) { protected function i_can_select_gradables($userid = -1) {
global $USER, $DB; global $USER, $DB;
if ($userid <= 0) { if ($userid <= 0) {
@ -87,6 +129,11 @@ class courseinfo {
return($usr && is_enrolled($this->coursecontext, $usr, 'local/treestudyplan:selectowngradables')); 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) { public static function get_contentitem($name) {
$contentitems = static::get_contentitems(); $contentitems = static::get_contentitems();
for ($i = 0; $i < count($contentitems); $i++) { for ($i = 0; $i < count($contentitems); $i++) {
@ -97,6 +144,11 @@ class courseinfo {
return null; 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) { public function __construct($id, studyitem $studyitem = null) {
global $DB; global $DB;
$this->studyitem = $studyitem; $this->studyitem = $studyitem;
@ -105,17 +157,32 @@ class courseinfo {
$this->coursecontext = \context_course::instance($this->course->id); $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) { public static function exists($id) {
global $DB; global $DB;
return is_numeric($id) && $DB->record_exists(self::TABLE, ['id' => $id]); 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) { public static function id_from_shortname($shortname) {
global $DB; global $DB;
return $DB->get_field(self::TABLE, "id", ['shortname' => $shortname]); 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) { public static function coursetiming($course) {
$now = time(); $now = time();
if ($now > $course->startdate) { 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() { public function timing() {
return self::coursetiming($this->course); 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() { public function displayname() {
$displayfield = get_config("local_treestudyplan", "display_field"); $displayfield = get_config("local_treestudyplan", "display_field");
if ($displayfield == "idnumber") { if ($displayfield == "idnumber") {
@ -158,6 +233,11 @@ class courseinfo {
return $this->course->shortname; 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) { public static function simple_structure($value = VALUE_REQUIRED) {
return new \external_single_structure([ return new \external_single_structure([
"id" => new \external_value(PARAM_INT, 'linked course id'), "id" => new \external_value(PARAM_INT, 'linked course id'),
@ -168,6 +248,10 @@ class courseinfo {
], 'referenced course information', $value); ], 'referenced course information', $value);
} }
/**
* Webservice model for basic info
* @return array Webservice data model
*/
public function simple_model() { public function simple_model() {
$contextinfo = new contextinfo($this->context); $contextinfo = new contextinfo($this->context);
$info = [ $info = [
@ -209,6 +293,8 @@ class courseinfo {
/** /**
* Webservice model for editor info * 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 * @return array Webservice data model
*/ */
public function editor_model(studyitem $studyitem = null, $usecorecompletioninfo = false) { public function editor_model(studyitem $studyitem = null, $usecorecompletioninfo = false) {
@ -235,10 +321,10 @@ class courseinfo {
]; ];
if (!$usecorecompletioninfo) { 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) { foreach ($gradables as $gradable) {
$info['grades'][] = $gradable->editor_model($studyitem); $info['grades'][] = $gradable->editor_model($studyitem ? $studyitem : $this->studyitem);
} }
} else { } else {
$cc = new corecompletioninfo($this->course); $cc = new corecompletioninfo($this->course);
@ -272,6 +358,7 @@ class courseinfo {
/** /**
* Webservice model for user info * 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
* @param bool $usecorecompletioninfo Whether to use corecompletion info instead of custom selected gradables
* @return array Webservice data model * @return array Webservice data model
*/ */
public function user_model($userid, $usecorecompletioninfo = false) { public function user_model($userid, $usecorecompletioninfo = false) {

View File

@ -102,7 +102,7 @@ class gradeinfo {
* Get the gradingscanner * Get the gradingscanner
* @return gradingscanner * @return gradingscanner
*/ */
public function get_gradingscanner() : gradingscanner{ public function get_gradingscanner() : gradingscanner {
return $this->gradingscanner; return $this->gradingscanner;
} }
@ -110,7 +110,7 @@ class gradeinfo {
* Get the grade's scale if applicable * Get the grade's scale if applicable
* @return grade_scale|null * @return grade_scale|null
*/ */
public function get_scale() : ?grade_scale{ public function get_scale() : ?grade_scale {
return $this->scale; return $this->scale;
} }
@ -468,7 +468,7 @@ class gradeinfo {
* @param studyitem $studyitem The studyitem to search for * @param studyitem $studyitem The studyitem to search for
* @return self[] Array of gradeinfo * @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; global $DB;
$table = 'local_treestudyplan_gradeinc'; $table = 'local_treestudyplan_gradeinc';
$list = []; $list = [];

View File

@ -233,7 +233,7 @@ class core_aggregator extends \local_treestudyplan\aggregator {
* @return int Aggregated completion as completion class constant * @return int Aggregated completion as completion class constant
*/ */
public function grade_completion(gradeinfo $gradeinfo, $userid) { 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; global $DB;
$table = "local_treestudyplan_gradecfg"; $table = "local_treestudyplan_gradecfg";

View File

@ -130,6 +130,10 @@ class period {
$this->page = studyplanpage::find_by_id($this->r->page_id); $this->page = studyplanpage::find_by_id($this->r->page_id);
} }
/**
* Return database identifier
* @return int
*/
public function id() { public function id() {
return $this->id; return $this->id;
} }
@ -142,10 +146,18 @@ class period {
return $this->page; return $this->page;
} }
/**
* Return short name
* @return string
*/
public function shortname() { public function shortname() {
return $this->r->shortname; return $this->r->shortname;
} }
/**
* Return full name
* @return string
*/
public function fullname() { public function fullname() {
return $this->r->fullname; return $this->r->fullname;
} }

View File

@ -26,7 +26,7 @@ require_once("$CFG->libdir/formslib.php");
require_once("$CFG->dirroot/local/treestudyplan/lib.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 { class reportinvite_form extends moodleform {
// Add elements to form. // Add elements to form.

View File

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

View File

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

View File

@ -65,14 +65,26 @@ class studyplan {
$this->aggregator = aggregator::create_or_default($this->r->aggregation, $this->r->aggregation_config); $this->aggregator = aggregator::create_or_default($this->r->aggregation, $this->r->aggregation_config);
} }
/**
* Return database identifier
* @return int
*/
public function id() { public function id() {
return $this->id; return $this->id;
} }
/**
* Return short name
* @return string
*/
public function shortname() { public function shortname() {
return $this->r->shortname; return $this->r->shortname;
} }
/**
* Return full name
* @return string
*/
public function name() { public function name() {
return $this->r->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 { public function context(): \context {
if (!isset($this->context)) { if (!isset($this->context)) {
@ -103,6 +116,11 @@ class studyplan {
return $this->context; 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) { public static function simple_structure($value = VALUE_REQUIRED) {
return new \external_single_structure([ return new \external_single_structure([
"id" => new \external_value(PARAM_INT, 'id of studyplan'), "id" => new \external_value(PARAM_INT, 'id of studyplan'),
@ -118,6 +136,10 @@ class studyplan {
], 'Basic studyplan info', $value); ], 'Basic studyplan info', $value);
} }
/**
* Webservice model for basic info
* @return array Webservice data model
*/
public function simple_model() { public function simple_model() {
$pages = []; $pages = [];
foreach ($this->pages() as $p) { foreach ($this->pages() as $p) {

View File

@ -60,6 +60,10 @@ class studyplanpage {
$this->studyplan = studyplan::find_by_id($this->r->studyplan_id); $this->studyplan = studyplan::find_by_id($this->r->studyplan_id);
} }
/**
* Return database identifier
* @return int
*/
public function id() { public function id() {
return $this->id; return $this->id;
} }
@ -68,6 +72,10 @@ class studyplanpage {
return $this->studyplan; return $this->studyplan;
} }
/**
* Return short name
* @return string
*/
public function shortname() { public function shortname() {
return $this->r->shortname; return $this->r->shortname;
} }
@ -76,6 +84,10 @@ class studyplanpage {
return $this->r->periods; return $this->r->periods;
} }
/**
* Return full name
* @return string
*/
public function fullname() { public function fullname() {
return $this->r->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) { public static function simple_structure($value = VALUE_REQUIRED) {
return new \external_single_structure([ return new \external_single_structure([
"id" => new \external_value(PARAM_INT, 'id of studyplan page'), "id" => new \external_value(PARAM_INT, 'id of studyplan page'),
@ -107,6 +124,10 @@ class studyplanpage {
], 'Studyplan page basic info', $value); ], 'Studyplan page basic info', $value);
} }
/**
* Webservice model for basic info
* @return array Webservice data model
*/
public function simple_model() { public function simple_model() {
return [ return [
'id' => $this->r->id, 'id' => $this->r->id,

View File

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

View File

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