MDL-63876 badges: Coding style

Add comments to document function params and template example context.

admin/tool/lp/amd/src/competencytree.js

@@ -141,7 +141,7 @@ define(['core/ajax', 'core/notification', 'core/templates', 'tool_lp/tree', 'too
          * @param {String} search The current search string
          * @param {String} selector The selector for the tree div
          * @param {Boolean} canmanage Can manage the competencies
-         * @param {Number} competencyid
+         * @param {Number} competencyid The id of the competency to show first
          */
         init: function(id, shortname, search, selector, canmanage, competencyid) {
             competencyFrameworkId = id;

admin/tool/lp/amd/src/form_competency_element.js

@@ -32,6 +32,7 @@ define(['jquery', 'tool_lp/competencypicker', 'core/ajax', 'core/notification',
      * Re-render the list of selected competencies.
      *
      * @method renderCompetencies
+     * @return {boolean}
      */
     var renderCompetencies = function() {
         var currentCompetencies = $('[data-action="competencies"]').val();
@@ -72,6 +73,8 @@ define(['jquery', 'tool_lp/competencypicker', 'core/ajax', 'core/notification',
      * Deselect a competency
      *
      * @method unpickCompetenciesHandler
+     * @param {Event} e
+     * @return {boolean}
      */
     var unpickCompetenciesHandler = function(e) {
         var currentCompetencies = $('[data-action="competencies"]').val().split(','),

admin/tool/lp/classes/output/manage_competencies_page.php

@@ -62,12 +62,16 @@ class manage_competencies_page implements renderable, templatable {
     /** @var context $pagecontext The page context. */
     protected $pagecontext = null;
 
+    /** @var \core_competency\competency $competency The competency to show when the page loads. */
+    protected $competency = null;
+
     /**
      * Construct this renderable.
      *
      * @param \core_competency\competency_framework $framework Competency framework.
      * @param string $search Search string.
      * @param context $pagecontext The page context.
+     * @param \core_competency\competency $competency The core competency to show when the page loads.
      */
     public function __construct($framework, $search, $pagecontext, $competency) {
         $this->framework = $framework;
@@ -98,7 +102,7 @@ public function export_for_template(renderer_base $output) {
         $data->pagecontextid = $this->pagecontext->id;
         $data->pluginbaseurl = (new moodle_url('/admin/tool/lp'))->out(true);
 
-        $competencyid = 0;
+        $data->competencyid = 0;
         if ($this->competency) {
             $data->competencyid = $this->competency->get('id');
         }

admin/tool/lp/classes/site_competencies_form_element.php

@@ -16,10 +16,10 @@
 
 
 /**
- * Course competencies element.
+ * Site competencies element.
  *
  * @package   tool_lp
- * @copyright 2016 Damyon Wiese
+ * @copyright 2019 Damyon Wiese
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
@@ -30,39 +30,36 @@
 require_once($CFG->libdir . '/form/hidden.php');
 
 /**
- * Course competencies element.
+ * Site competencies element.
  *
  * @package   tool_lp
- * @copyright 2016 Damyon Wiese
+ * @copyright 2019 Damyon Wiese
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class tool_lp_site_competencies_form_element extends MoodleQuickForm_hidden {
 
     /**
      * Constructor
      *
-     * @param string $elementName Element name
-     * @param mixed $elementLabel Label(s) for an element
-     * @param array $options Options to control the element's display
+     * @param string $elementname Element name.
+     * @param string $value The element value.
      * @param mixed $attributes Either a typical HTML attribute string or an associative array.
      */
-    public function __construct($elementName=null, $value='', $attributes=null) {
-        global $OUTPUT;
-
-        if ($elementName == null) {
+    public function __construct($elementname=null, $value='', $attributes=null) {
+        if ($elementname == null) {
             // This is broken quickforms messing with the constructors.
             return;
         }
-        $attributes = array_merge(['data-action' => 'competencies'], $attributes?$attributes:[]);
+        $attributes = array_merge(['data-action' => 'competencies'], $attributes ? $attributes : []);
 
-        parent::__construct($elementName, $value, $attributes);
+        parent::__construct($elementname, $value, $attributes);
         $this->setType('hidden');
     }
 
     /**
      * Generate the hidden field and the controls to show and pick the competencies.
      */
-    function toHtml(){
+    public function toHtml() {
         global $PAGE;
 
         $html = parent::toHTML();
@@ -77,7 +74,9 @@ function toHtml(){
             $html .= '<div class="col-md-9">';
             $html .= '<div data-region="competencies"></div>';
             $html .= '<div class="mt-3">';
-            $html .= '<a class="btn btn-secondary" role="button" data-action="select-competencies">' . get_string('addcompetency', 'tool_lp') . '</a>';
+            $html .= '<a class="btn btn-secondary" role="button" data-action="select-competencies">';
+            $html .= get_string('addcompetency', 'tool_lp');
+            $html .= '</a>';
             $html .= '</div>';
             $html .= '</div>';
             $html .= '</div>';
@@ -88,12 +87,12 @@ function toHtml(){
     /**
      * Accepts a renderer
      *
-     * @param object     An HTML_QuickForm_Renderer object
-     * @access public
+     * @param HTML_QuickForm_Renderer $renderer the renderer for the element.
+     * @param boolean $required not used.
+     * @param string $error not used.
      * @return void
      */
-    function accept(&$renderer, $required=false, $error=null)
-    {
+    public function accept(&$renderer, $required=false, $error=null) {
         $renderer->renderElement($this, false, '');
     }
 }

admin/tool/lp/lib.php

@@ -220,6 +220,13 @@ function tool_lp_get_fontawesome_icon_map() {
 
 /**
  * Render a short bit of information about a competency.
+ *
+ * @param \core_competency\competency $competency The competency to show.
+ * @param \core_competency\competency_framework $framework The competency framework.
+ * @param boolean $includerelated If true, show related competencies.
+ * @param boolean $includecourses If true, show courses using this competency.
+ * @param boolean $skipenabled If true, show this competency even if competencies are disabled.
+ * @return string The html summary for the competency.
  */
 function tool_lp_render_competency_summary(\core_competency\competency $competency,
                                            \core_competency\competency_framework $framework,

admin/tool/lp/templates/manage_competencies_page.mustache

@@ -15,6 +15,8 @@
     along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 }}
 {{!
+    @template tool_lp/manage_competencies_page
+
     Manage competencies template.
 
     Classes required for JS:
@@ -25,10 +27,15 @@
     * data-region=term
     * data-region=selected-competency
 
-    Context variables required for this template:
-    * framework -
-    * competencies - array of objects containing id, shortname, idnumber, sortorder, parentid, competencyframeworkid, path
-    * canmanage - true if this user has permission to manage the competencies
+    Example context (json):
+    {
+        "framework": { 
+            "description": "Framework",
+            "id": 0
+        },
+        "competencies": [],
+        "canmanage": false
+    }
 }}
 <div data-region="managecompetencies">
 <h2>

badges/classes/observer.php

@@ -86,7 +86,6 @@ public static function competency_criteria_review(\core\event\competency_evidenc
 
             $ucid = $event->other['usercompetencyid'];
             $cid = $event->other['competencyid'];
-            $eventdata = $event->get_record_snapshot('competency_usercomp', $ucid);
             $userid = $event->relateduserid;
 
             if ($rs = $DB->get_records('badge_criteria_param', array('name' => 'competency_' . $cid, 'value' => $cid))) {
@@ -122,7 +121,6 @@ public static function course_criteria_review(\core\event\course_completed $even
         if (!empty($CFG->enablebadges)) {
             require_once($CFG->dirroot.'/lib/badgeslib.php');
 
-            $eventdata = $event->get_record_snapshot('course_completions', $event->objectid);
             $userid = $event->relateduserid;
             $courseid = $event->courseid;
 

badges/criteria/award_criteria_competency.php

@@ -35,23 +35,20 @@
  */
 class award_criteria_competency extends award_criteria {
 
-    /* @var int Criteria [BADGE_CRITERIA_TYPE_COMPETENCY] */
+    /* @var int The criteria type */
     public $criteriatype = BADGE_CRITERIA_TYPE_COMPETENCY;
+    /* @var string a required param */
     public $required_param = 'competency';
+    /* @var array no optional params */
     public $optional_params = [];
 
 
-    public $required_param = 'competency';
-    public $self_validation = true;
-    public $optional_params = array('');
-
     /**
      * Get criteria details for displaying to users
      * @param string $short Print short version of criteria
      * @return string
      */
     public function get_details($short = '') {
-        global $DB, $OUTPUT;
         $output = array();
 
         foreach ($this->params as $p) {
@@ -80,9 +77,10 @@ public function get_details($short = '') {
     /**
      * Add appropriate new criteria options to the form
      * @param object $mform moodle form
+     * @return array First item is a boolean to indicate an error and the second is the error message.
      */
     public function get_options(&$mform) {
-        global $DB, $PAGE;
+        global $DB;
         $none = false;
         $availablebadges = null;
 
@@ -180,11 +178,9 @@ public function review($userid, $filtered = false) {
         }
 
         foreach ($this->params as $param) {
-            $found = false;
             $proficiency = false;
             foreach ($existing as $usercompetency) {
                 if ($usercompetency->get('competencyid') == $param['competency']) {
-                    $found = true;
                     $proficiency = $usercompetency->get('proficiency');
                 }
             }
@@ -240,7 +236,6 @@ public function get_completed_criteria_sql() {
             }
             $where .= ' AND uc2.proficiency = :isproficient ';
             $params['isproficient'] = true;
-            return array($join, $where, $params);
         } else {
 
             // User has received ALL of the required competencies (we have to join on each one).
@@ -256,7 +251,6 @@ public function get_completed_criteria_sql() {
                 $params['isproficient' . $joincount] = true;
             }
 
-            return array($join, $where, $params);
         }
         return array($join, $where, $params);
     }

badges/criteria_form.php

@@ -78,7 +78,10 @@ public function validation($data, $files) {
         $errors = parent::validation($data, $files);
         $addcourse = $this->_customdata['addcourse'];
 
-        if (!$addcourse && isset($this->_customdata['criteria']->required_param) && !isset($this->_customdata['criteria']->self_validation)) {
+        if (!$addcourse &&
+                isset($this->_customdata['criteria']->required_param) &&
+                !isset($this->_customdata['criteria']->self_validation)) {
+
             $required = $this->_customdata['criteria']->required_param;
             $pattern1 = '/^' . $required . '_(\d+)$/';
             $pattern2 = '/^' . $required . '_(\w+)$/';

competency/upgrade.txt

@@ -1,6 +1,11 @@
 This files describes API changes in /competency/*. The information provided
 here is intended especially for developers.
 
+=== 3.7 ===
+* tool_lp can render the ui for a competency summary or a competency picker.
+    Use get_plugins_with_function('competency_picker') or
+        get_plugins_with_function('render_competency_summary') to call it.
+
 === 3.3 ===
 
 * Deprecated classes and their new equivalent:

lib/badgeslib.php

@@ -853,6 +853,18 @@ public function get_alignments() {
         return $DB->get_records('badge_alignment', array('badgeid' => $this->id));
     }
 
+    /**
+     * Get alignments of badge.
+     *
+     * @deprecated since Moodle 3.7 see MDL-63876
+     * @return array List content alignments.
+     */
+    public function get_alignment() {
+        debugging('Use of get_alignment is deprecated. Call get_alignments instead.', DEBUG_DEVELOPER);
+
+        return $this->get_alignments();
+    }
+
     /**
      * Insert/update Endorsement information of badge.
      *
@@ -1546,6 +1558,7 @@ function badges_setup_backpack_js() {
 /**
  * Return all the enabled criteria types for this site.
  *
+ * @param boolean $enabled
  * @return array
  */
 function badges_list_criteria($enabled = true) {