MDL-62342 privacy: Use singular/plural form in labels
[moodle.git] / admin / tool / policy / classes / external.php
CommitLineData
6109f234
SA
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 * Class containing the external API functions functions for the Policy tool.
19 *
20 * @package tool_policy
21 * @copyright 2018 Sara Arjona (sara@moodle.com)
22 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23 */
24
25namespace tool_policy;
26
27defined('MOODLE_INTERNAL') || die();
28
29use coding_exception;
30use context_system;
31use context_user;
32use core\invalid_persistent_exception;
33use dml_exception;
34use external_api;
35use external_description;
36use external_function_parameters;
37use external_single_structure;
38use external_value;
39use external_warnings;
40use invalid_parameter_exception;
41use moodle_exception;
42use restricted_context_exception;
43use tool_policy\api;
44use tool_policy\form\accept_policy;
45
46/**
47 * Class external.
48 *
49 * The external API for the Policy tool.
50 *
51 * @copyright 2018 Sara Arjona (sara@moodle.com)
52 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
53 */
54class external extends external_api {
55
56 /**
57 * Parameter description for get_policy_version_parameters().
58 *
59 * @return external_function_parameters
60 */
61 public static function get_policy_version_parameters() {
62 return new external_function_parameters([
63 'versionid' => new external_value(PARAM_INT, 'The policy version ID', VALUE_REQUIRED),
64 'behalfid' => new external_value(PARAM_INT, 'The id of user on whose behalf the user is viewing the policy',
65 VALUE_DEFAULT, 0)
66 ]);
67 }
68
69 /**
70 * Fetch the details of a policy version.
71 *
72 * @param int $versionid The policy version ID.
73 * @param int $behalfid The id of user on whose behalf the user is viewing the policy.
74 * @return array
75 * @throws coding_exception
76 * @throws dml_exception
77 * @throws invalid_parameter_exception
78 * @throws restricted_context_exception
79 * @throws moodle_exception
80 */
81 public static function get_policy_version($versionid, $behalfid = null) {
82 global $PAGE;
83
84 $result = [];
85 $warnings = [];
86 $params = external_api::validate_parameters(self::get_policy_version_parameters(), [
87 'versionid' => $versionid,
88 'behalfid' => $behalfid
89 ]);
90 $versionid = $params['versionid'];
91 $behalfid = $params['behalfid'];
92
93 $context = context_system::instance();
94 $PAGE->set_context($context);
95
96 try {
97 // Validate if the user has access to the policy version.
98 $version = api::get_policy_version($versionid);
99 if (!api::can_user_view_policy_version($version, $behalfid)) {
100 $warnings[] = [
101 'item' => $versionid,
102 'warningcode' => 'errorusercantviewpolicyversion',
103 'message' => get_string('errorusercantviewpolicyversion', 'tool_policy')
104 ];
105 } else if (!empty($version)) {
106 $version = api::get_policy_version($versionid);
107 $policy['name'] = $version->name;
108 $policy['versionid'] = $versionid;
109 list($policy['content'], $notusedformat) = external_format_text(
110 $version->content,
111 $version->contentformat,
112 SYSCONTEXTID,
113 'tool_policy',
114 'policydocumentcontent',
115 $version->id
116 );
117 $result['policy'] = $policy;
118 }
119 } catch (moodle_exception $e) {
120 $warnings[] = [
121 'item' => $versionid,
122 'warningcode' => 'errorpolicyversionnotfound',
123 'message' => get_string('errorpolicyversionnotfound', 'tool_policy')
124 ];
125 }
126
127 return [
128 'result' => $result,
129 'warnings' => $warnings
130 ];
131 }
132
133 /**
134 * Parameter description for get_policy_version().
135 *
136 * @return external_description
137 */
138 public static function get_policy_version_returns() {
139 return new external_single_structure([
140 'result' => new external_single_structure([
141 'policy' => new external_single_structure([
142 'name' => new external_value(PARAM_RAW, 'The policy version name', VALUE_OPTIONAL),
143 'versionid' => new external_value(PARAM_INT, 'The policy version id', VALUE_OPTIONAL),
144 'content' => new external_value(PARAM_RAW, 'The policy version content', VALUE_OPTIONAL)
145 ], 'Policy information', VALUE_OPTIONAL)
146 ]),
147 'warnings' => new external_warnings()
148 ]);
149 }
150
151 /**
152 * Describes the parameters for submit_create_group_form webservice.
153 * @return external_function_parameters
154 */
155 public static function submit_accept_on_behalf_parameters() {
156 return new external_function_parameters(
157 array(
158 'jsonformdata' => new external_value(PARAM_RAW, 'The data from the create group form, encoded as a json array')
159 )
160 );
161 }
162
163 /**
164 * Submit the create group form.
165 *
166 * @param string $jsonformdata The data from the form, encoded as a json array.
167 * @return int new group id.
168 */
169 public static function submit_accept_on_behalf($jsonformdata) {
170 // We always must pass webservice params through validate_parameters.
171 $params = self::validate_parameters(self::submit_accept_on_behalf_parameters(),
172 ['jsonformdata' => $jsonformdata]);
173
174 self::validate_context(context_system::instance());
175
176 $serialiseddata = json_decode($params['jsonformdata']);
177
178 $data = array();
179 parse_str($serialiseddata, $data);
180
181 // The last param is the ajax submitted data.
182 $mform = new accept_policy(null, $data, 'post', '', null, true, $data);
183
184 // Do the action.
185 $mform->process();
186
187 return true;
188 }
189
190 /**
191 * Returns description of method result value.
192 *
193 * @return external_description
194 * @since Moodle 3.0
195 */
196 public static function submit_accept_on_behalf_returns() {
197 return new external_value(PARAM_BOOL, 'success');
198 }
199}