grade/externallib.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 /**
  18  * External assign API
  19  *
  20  * @package    core_grade
  21  * @since      Moodle 2.5
  22  * @copyright  2013 Paul Charsley
  23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24  */
  25
  26 defined('MOODLE_INTERNAL') || die;
  27
  28 require_once("$CFG->libdir/externallib.php");
  29 require_once("$CFG->dirroot/grade/grading/lib.php");
  30
  31 /**
  32  * core grade functions
  33  */
  34 class core_grade_external extends external_api {
  35
  36     /**
  37      * Describes the parameters for get_definitions
  38      * @return external_function_parameters
  39      * @since Moodle 2.5
  40      */
  41     public static function get_definitions_parameters () {
  42         return new external_function_parameters(
  43             array(
  44                 'cmids' => new external_multiple_structure(
  45                     new external_value(PARAM_INT, 'course module id'), '1 or more course module ids'),
  46                 'areaname' => new external_value(PARAM_AREA, 'area name'),
  47                 'activeonly' => new external_value(PARAM_BOOL, 'Only the active method', VALUE_DEFAULT, 0)
  48             )
  49         );
  50     }
  51
  52     /**
  53      * Returns the definitions for the requested course module ids
  54      * @param array of ints $cmids
  55      * @param string $areaname
  56      * @param boolean $activeonly default is false, if true, only the active method is returned
  57      * @return array of areas with definitions for each requested course module id
  58      * @since Moodle 2.5
  59      */
  60     public static function get_definitions ($cmids, $areaname, $activeonly = false) {
  61         global $DB, $CFG;
  62         require_once("$CFG->dirroot/grade/grading/form/lib.php");
  63         $params = self::validate_parameters(self::get_definitions_parameters(),
  64                       array('cmids' => $cmids,
  65                             'areaname' => $areaname,
  66                             'activeonly' => $activeonly));
  67         $warnings = array();
  68         $areas = array();
  69         foreach ($params['cmids'] as $cmid) {
  70             $context = context_module::instance($cmid);
  71             try {
  72                 self::validate_context($context);
  73             } catch (Exception $e) {
  74                 $warnings[] = array(
  75                     'item' => 'module',
  76                     'itemid' => $cmid,
  77                     'message' => 'No access rights in module context',
  78                     'warningcode' => '1'
  79                 );
  80                 continue;
  81             }
  82             // Check if the user has managegradingforms capability.
  83             $isgradingmethodmanager = false;
  84             if (has_capability('moodle/grade:managegradingforms', $context)) {
  85                 $isgradingmethodmanager = true;
  86             }
  87             $module = get_coursemodule_from_id('', $cmid, 0, false, MUST_EXIST);
  88             $componentname = "mod_".$module->modname;
  89
  90             // Get the grading manager.
  91             $gradingmanager = get_grading_manager($context, $componentname, $params['areaname']);
  92             // Get the controller for each grading method.
  93             $methods = array();
  94             if ($params['activeonly'] == true) {
  95                 $methods[] = $gradingmanager->get_active_method();
  96             } else {
  97                 $methods = array_keys($gradingmanager->get_available_methods(false));
  98             }
  99
 100             $area = array();
 101             $area['cmid'] = $cmid;
 102             $area['contextid'] = $context->id;
 103             $area['component'] = $componentname;
 104             $area['activemethod'] = $gradingmanager->get_active_method();
 105             $area['definitions'] = array();
 106
 107             foreach ($methods as $method) {
 108                 $controller = $gradingmanager->get_controller($method);
 109                 $def = $controller->get_definition(true);
 110                 if ($def == false) {
 111                     continue;
 112                 }
 113                 if ($isgradingmethodmanager == false) {
 114                     $isviewable = true;
 115                     if ($def->status != gradingform_controller::DEFINITION_STATUS_READY) {
 116                         $warnings[] = array(
 117                             'item' => 'module',
 118                             'itemid' => $cmid,
 119                             'message' => 'Capability moodle/grade:managegradingforms required to view draft definitions',
 120                             'warningcode' => '1'
 121                         );
 122                         $isviewable = false;
 123                     }
 124                     if (!empty($def->options)) {
 125                         $options = json_decode($def->options);
 126                         if (isset($options->alwaysshowdefinition) &&
 127                                 $options->alwaysshowdefinition == 0) {
 128                             $warnings[] = array(
 129                                 'item' => 'module',
 130                                 'itemid' => $cmid,
 131                                 'message' => 'Capability moodle/grade:managegradingforms required to preview definition',
 132                                 'warningcode' => '1'
 133                             );
 134                             $isviewable = false;
 135                         }
 136                     }
 137                     if ($isviewable == false) {
 138                         continue;
 139                     }
 140                 }
 141                 $definition = array();
 142                 $definition['id'] = $def->id;
 143                 $definition['method'] = $method;
 144                 $definition['name'] = $def->name;
 145                 $definition['description'] = $def->description;
 146                 $definition['descriptionformat'] = $def->descriptionformat;
 147                 $definition['status'] = $def->status;
 148                 $definition['copiedfromid'] = $def->copiedfromid;
 149                 $definition['timecreated'] = $def->timecreated;
 150                 $definition['usercreated'] = $def->usercreated;
 151                 $definition['timemodified'] = $def->timemodified;
 152                 $definition['usermodified'] = $def->usermodified;
 153                 $definition['timecopied'] = $def->timecopied;
 154                 // Format the description text field.
 155                 $formattedtext = external_format_text($definition['description'],
 156                                                       $definition['descriptionformat'],
 157                                                       $context->id,
 158                                                       $componentname,
 159                                                       'description',
 160                                                       $def->id);
 161                 $definition['description'] = $formattedtext[0];
 162                 $definition['descriptionformat'] = $formattedtext[1];
 163
 164                 $details = $controller->get_external_definition_details();
 165                 $items = array();
 166                 foreach ($details as $key => $value) {
 167                     $items[$key] = self::format_text($def->{$key}, $context->id, $componentname, $def->id);
 168                 }
 169                 $definition[$method] = $items;
 170                 $area['definitions'][] = $definition;
 171             }
 172             $areas[] = $area;
 173         }
 174         $result = array(
 175             'areas' => $areas,
 176             'warnings' => $warnings
 177         );
 178         return $result;
 179     }
 180
 181     /**
 182      * Recursively processes all elements in an array and runs external_format_text()on
 183      * all elements which have a text field and associated format field with a key name
 184      * that ends with the text 'format'. The modified array is returned.
 185      * @param array $items the array to be processed
 186      * @param int $contextid
 187      * @param string $componentname
 188      * @param int $itemid
 189      * @see external_format_text in lib/externallib.php
 190      * @return array the input array with all fields formatted
 191      */
 192     private static function format_text($items, $contextid, $componentname, $itemid) {
 193         $formatkeys = array();
 194         foreach ($items as $key => $value) {
 195             if (!is_array($value) && substr_compare($key, 'format', -6, 6) === 0) {
 196                 $formatkeys[] = $key;
 197             }
 198         }
 199         foreach ($formatkeys as $formatkey) {
 200             $descriptionkey = substr($formatkey, 0, -6);
 201             $formattedtext = external_format_text($items[$descriptionkey],
 202                                                   $items[$formatkey],
 203                                                   $contextid,
 204                                                   $componentname,
 205                                                   'description',
 206                                                   $itemid);
 207             $items[$descriptionkey] = $formattedtext[0];
 208             $items[$formatkey] = $formattedtext[1];
 209         }
 210         foreach ($items as $key => $value) {
 211             if (is_array($value)) {
 212                 $items[$key] = self::format_text($value, $contextid, $componentname, $itemid);
 213             }
 214         }
 215         return $items;
 216     }
 217
 218     /**
 219      * Creates a grading area
 220      * @return external_single_structure
 221      * @since  Moodle 2.5
 222      */
 223     private static function grading_area() {
 224         return new external_single_structure(
 225             array (
 226                 'cmid'    => new external_value(PARAM_INT, 'course module id'),
 227                 'contextid'  => new external_value(PARAM_INT, 'context id'),
 228                 'component' => new external_value(PARAM_TEXT, 'component name'),
 229                 'activemethod' => new external_value(PARAM_TEXT, 'active method', VALUE_OPTIONAL),
 230                 'definitions'  => new external_multiple_structure(self::definition(), 'definitions')
 231             )
 232         );
 233     }
 234
 235     /**
 236      * creates a grading form definition
 237      * @return external_single_structure
 238      * @since  Moodle 2.5
 239      */
 240     private static function definition() {
 241         global $CFG;
 242         $definition = array();
 243         $definition['id']                = new external_value(PARAM_INT, 'definition id');
 244         $definition['method']            = new external_value(PARAM_TEXT, 'method');
 245         $definition['name']              = new external_value(PARAM_TEXT, 'name');
 246         $definition['description']       = new external_value(PARAM_RAW, 'description');
 247         $definition['descriptionformat'] = new external_format_value('description');
 248         $definition['status']            = new external_value(PARAM_INT, 'status');
 249         $definition['copiedfromid']      = new external_value(PARAM_INT, 'copied from id', VALUE_OPTIONAL);
 250         $definition['timecreated']       = new external_value(PARAM_INT, 'creation time');
 251         $definition['usercreated']       = new external_value(PARAM_INT, 'user who created definition');
 252         $definition['timemodified']      = new external_value(PARAM_INT, 'last modified time');
 253         $definition['usermodified']      = new external_value(PARAM_INT, 'user who modified definition');
 254         $definition['timecopied']        = new external_value(PARAM_INT, 'time copied', VALUE_OPTIONAL);
 255         foreach (self::get_grading_methods() as $method) {
 256             require_once($CFG->dirroot.'/grade/grading/form/'.$method.'/lib.php');
 257             $details  = call_user_func('gradingform_'.$method.'_controller::get_external_definition_details');
 258             if ($details != null) {
 259                 $items = array();
 260                 foreach ($details as $key => $value) {
 261                     $details[$key]->required = VALUE_OPTIONAL;
 262                     $items[$key] = $value;
 263                 }
 264                 $definition[$method] = new external_single_structure($items, 'items', VALUE_OPTIONAL);
 265             }
 266         }
 267         return new external_single_structure($definition);
 268     }
 269
 270     /**
 271      * Describes the get_definitions return value
 272      * @return external_single_structure
 273      * @since Moodle 2.5
 274      */
 275     public static function get_definitions_returns() {
 276         return new external_single_structure(
 277             array(
 278                 'areas' => new external_multiple_structure(self::grading_area(), 'list of grading areas'),
 279                 'warnings' => new external_warnings()
 280             )
 281         );
 282     }
 283
 284     /**
 285      * @return array of available grading methods
 286      * @since Moodle 2.5
 287      */
 288     private static function get_grading_methods() {
 289         $methods = array_keys(grading_manager::available_methods(false));
 290         return $methods;
 291     }
 292
 293 }