[moodle.git] / grade / externallib.php

<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * External assign API
 *
 * @package    core_grade
 * @since      Moodle 2.5
 * @copyright  2013 Paul Charsley
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

defined('MOODLE_INTERNAL') || die;

require_once("$CFG->libdir/externallib.php");
require_once("$CFG->dirroot/grade/grading/lib.php");

/**
 * core grade functions
 */
class core_grade_external extends external_api {

    /**
     * Describes the parameters for get_definitions
     * @return external_function_parameters
     * @since Moodle 2.5
     */
    public static function get_definitions_parameters () {
        return new external_function_parameters(
            array(
                'cmids' => new external_multiple_structure(
                    new external_value(PARAM_INT, 'course module id'), '1 or more course module ids'),
                'areaname' => new external_value(PARAM_AREA, 'area name'),
                'activeonly' => new external_value(PARAM_BOOL, 'Only the active method', VALUE_DEFAULT, 0)
            )
        );
    }

    /**
     * Returns the definitions for the requested course module ids
     * @param array of ints $cmids
     * @param string $areaname
     * @param boolean $activeonly default is false, if true, only the active method is returned
     * @return array of areas with definitions for each requested course module id
     * @since Moodle 2.5
     */
    public static function get_definitions ($cmids, $areaname, $activeonly = false) {
        global $DB, $CFG;
        require_once("$CFG->dirroot/grade/grading/form/lib.php");
        $params = self::validate_parameters(self::get_definitions_parameters(),
                      array('cmids' => $cmids,
                            'areaname' => $areaname,
                            'activeonly' => $activeonly));
        $warnings = array();
        $areas = array();
        foreach ($params['cmids'] as $cmid) {
            $context = context_module::instance($cmid);
            try {
                self::validate_context($context);
            } catch (Exception $e) {
                $warnings[] = array(
                    'item' => 'module',
                    'itemid' => $cmid,
                    'message' => 'No access rights in module context',
                    'warningcode' => '1'
                );
                continue;
            }
            // Check if the user has managegradingforms capability.
            $isgradingmethodmanager = false;
            if (has_capability('moodle/grade:managegradingforms', $context)) {
                $isgradingmethodmanager = true;
            }
            $module = get_coursemodule_from_id('', $cmid, 0, false, MUST_EXIST);
            $componentname = "mod_".$module->modname;

            // Get the grading manager.
            $gradingmanager = get_grading_manager($context, $componentname, $params['areaname']);
            // Get the controller for each grading method.
            $methods = array();
            if ($params['activeonly'] == true) {
                $methods[] = $gradingmanager->get_active_method();
            } else {
                $methods = array_keys($gradingmanager->get_available_methods(false));
            }

            $area = array();
            $area['cmid'] = $cmid;
            $area['contextid'] = $context->id;
            $area['component'] = $componentname;
            $area['activemethod'] = $gradingmanager->get_active_method();
            $area['definitions'] = array();

            foreach ($methods as $method) {
                $controller = $gradingmanager->get_controller($method);
                $def = $controller->get_definition(true);
                if ($def == false) {
                    continue;
                }
                if ($isgradingmethodmanager == false) {
                    $isviewable = true;
                    if ($def->status != gradingform_controller::DEFINITION_STATUS_READY) {
                        $warnings[] = array(
                            'item' => 'module',
                            'itemid' => $cmid,
                            'message' => 'Capability moodle/grade:managegradingforms required to view draft definitions',
                            'warningcode' => '1'
                        );
                        $isviewable = false;
                    }
                    if (!empty($def->options)) {
                        $options = json_decode($def->options);
                        if (isset($options->alwaysshowdefinition) &&
                                $options->alwaysshowdefinition == 0) {
                            $warnings[] = array(
                                'item' => 'module',
                                'itemid' => $cmid,
                                'message' => 'Capability moodle/grade:managegradingforms required to preview definition',
                                'warningcode' => '1'
                            );
                            $isviewable = false;
                        }
                    }
                    if ($isviewable == false) {
                        continue;
                    }
                }
                $definition = array();
                $definition['id'] = $def->id;
                $definition['method'] = $method;
                $definition['name'] = $def->name;
                $definition['description'] = $def->description;
                $definition['descriptionformat'] = $def->descriptionformat;
                $definition['status'] = $def->status;
                $definition['copiedfromid'] = $def->copiedfromid;
                $definition['timecreated'] = $def->timecreated;
                $definition['usercreated'] = $def->usercreated;
                $definition['timemodified'] = $def->timemodified;
                $definition['usermodified'] = $def->usermodified;
                $definition['timecopied'] = $def->timecopied;
                // Format the description text field.
                $formattedtext = external_format_text($definition['description'],
                                                      $definition['descriptionformat'],
                                                      $context->id,
                                                      $componentname,
                                                      'description',
                                                      $def->id);
                $definition['description'] = $formattedtext[0];
                $definition['descriptionformat'] = $formattedtext[1];

                $details = $controller->get_external_definition_details();
                $items = array();
                foreach ($details as $key => $value) {
                    $items[$key] = self::format_text($def->{$key}, $context->id, $componentname, $def->id);
                }
                $definition[$method] = $items;
                $area['definitions'][] = $definition;
            }
            $areas[] = $area;
        }
        $result = array(
            'areas' => $areas,
            'warnings' => $warnings
        );
        return $result;
    }

    /**
     * Recursively processes all elements in an array and runs external_format_text()on
     * all elements which have a text field and associated format field with a key name
     * that ends with the text 'format'. The modified array is returned.
     * @param array $items the array to be processed
     * @param int $contextid
     * @param string $componentname
     * @param int $itemid
     * @see external_format_text in lib/externallib.php
     * @return array the input array with all fields formatted
     */
    private static function format_text($items, $contextid, $componentname, $itemid) {
        $formatkeys = array();
        foreach ($items as $key => $value) {
            if (!is_array($value) && substr_compare($key, 'format', -6, 6) === 0) {
                $formatkeys[] = $key;
            }
        }
        foreach ($formatkeys as $formatkey) {
            $descriptionkey = substr($formatkey, 0, -6);
            $formattedtext = external_format_text($items[$descriptionkey],
                                                  $items[$formatkey],
                                                  $contextid,
                                                  $componentname,
                                                  'description',
                                                  $itemid);
            $items[$descriptionkey] = $formattedtext[0];
            $items[$formatkey] = $formattedtext[1];
        }
        foreach ($items as $key => $value) {
            if (is_array($value)) {
                $items[$key] = self::format_text($value, $contextid, $componentname, $itemid);
            }
        }
        return $items;
    }

    /**
     * Creates a grading area
     * @return external_single_structure
     * @since  Moodle 2.5
     */
    private static function grading_area() {
        return new external_single_structure(
            array (
                'cmid'    => new external_value(PARAM_INT, 'course module id'),
                'contextid'  => new external_value(PARAM_INT, 'context id'),
                'component' => new external_value(PARAM_TEXT, 'component name'),
                'activemethod' => new external_value(PARAM_TEXT, 'active method', VALUE_OPTIONAL),
                'definitions'  => new external_multiple_structure(self::definition(), 'definitions')
            )
        );
    }

    /**
     * creates a grading form definition
     * @return external_single_structure
     * @since  Moodle 2.5
     */
    private static function definition() {
        global $CFG;
        $definition = array();
        $definition['id']                = new external_value(PARAM_INT, 'definition id');
        $definition['method']            = new external_value(PARAM_TEXT, 'method');
        $definition['name']              = new external_value(PARAM_TEXT, 'name');
        $definition['description']       = new external_value(PARAM_RAW, 'description');
        $definition['descriptionformat'] = new external_format_value('description');
        $definition['status']            = new external_value(PARAM_INT, 'status');
        $definition['copiedfromid']      = new external_value(PARAM_INT, 'copied from id', VALUE_OPTIONAL);
        $definition['timecreated']       = new external_value(PARAM_INT, 'creation time');
        $definition['usercreated']       = new external_value(PARAM_INT, 'user who created definition');
        $definition['timemodified']      = new external_value(PARAM_INT, 'last modified time');
        $definition['usermodified']      = new external_value(PARAM_INT, 'user who modified definition');
        $definition['timecopied']        = new external_value(PARAM_INT, 'time copied', VALUE_OPTIONAL);
        foreach (self::get_grading_methods() as $method) {
            require_once($CFG->dirroot.'/grade/grading/form/'.$method.'/lib.php');
            $details  = call_user_func('gradingform_'.$method.'_controller::get_external_definition_details');
            if ($details != null) {
                $items = array();
                foreach ($details as $key => $value) {
                    $details[$key]->required = VALUE_OPTIONAL;
                    $items[$key] = $value;
                }
                $definition[$method] = new external_single_structure($items, 'items', VALUE_OPTIONAL);
            }
        }
        return new external_single_structure($definition);
    }

    /**
     * Describes the get_definitions return value
     * @return external_single_structure
     * @since Moodle 2.5
     */
    public static function get_definitions_returns() {
        return new external_single_structure(
            array(
                'areas' => new external_multiple_structure(self::grading_area(), 'list of grading areas'),
                'warnings' => new external_warnings()
            )
        );
    }

    /**
     * @return array of available grading methods
     * @since Moodle 2.5
     */
    private static function get_grading_methods() {
        $methods = array_keys(grading_manager::available_methods(false));
        return $methods;
    }

}
Commit	Line	Data
3f0ea6d8 PC	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(
27a1d25f DW	117	'item' => 'module',
	118	'itemid' => $cmid,
	119	'message' => 'Capability moodle/grade:managegradingforms required to view draft definitions',
	120	'warningcode' => '1'
	121	);
3f0ea6d8 PC	122	$isviewable = false;
	123	}
	124	if (!empty($def->options)) {
	125	$options = json_decode($def->options);
27a1d25f DW	126	if (isset($options->alwaysshowdefinition) &&
27a1d25f DW	127	$options->alwaysshowdefinition == 0) {
3f0ea6d8	128	$warnings[] = array(
27a1d25f DW	129	'item' => 'module',
	130	'itemid' => $cmid,
	131	'message' => 'Capability moodle/grade:managegradingforms required to preview definition',
	132	'warningcode' => '1'
	133	);
3f0ea6d8 PC	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.
27a1d25f DW	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
3f0ea6d8 PC	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);
27a1d25f DW	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];
3f0ea6d8	209	}
27a1d25f	210	foreach ($items as $key => $value) {
3f0ea6d8	211	if (is_array($value)) {
27a1d25f	212	$items[$key] = self::format_text($value, $contextid, $componentname, $itemid);
3f0ea6d8 PC	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	}