MDL-36541 modify get_groupings to optionally return associated groups

diff --git a/group/externallib.php b/group/externallib.php
index 5963c6e..48d656f 100644 (file)
--- a/group/externallib.php
+++ b/group/externallib.php
@@ -760,6 +760,7 @@ class core_group_external extends external_api {
             array(
                 'groupingids' => new external_multiple_structure(new external_value(PARAM_INT, 'grouping ID')
                         , 'List of grouping id. A grouping id is an integer.'),
+                'returngroups' => new external_value(PARAM_BOOL, 'return associated groups', VALUE_DEFAULT, 0)
             )
         );
     }
@@ -768,15 +769,18 @@ class core_group_external extends external_api {
      * Get groupings definition specified by ids
      *
      * @param array $groupingids arrays of grouping ids
+     * @param boolean $returngroups return the associated groups if true. The default is false.
      * @return array of grouping objects (id, courseid, name)
      * @since Moodle 2.3
      */
-    public static function get_groupings($groupingids) {
-        global $CFG;
+    public static function get_groupings($groupingids, $returngroups = false) {
+        global $CFG, $DB;
         require_once("$CFG->dirroot/group/lib.php");
         require_once("$CFG->libdir/filelib.php");
 
-        $params = self::validate_parameters(self::get_groupings_parameters(), array('groupingids'=>$groupingids));
+        $params = self::validate_parameters(self::get_groupings_parameters(),
+                                            array('groupingids' => $groupingids,
+                                                  'returngroups' => $returngroups));
 
         $groupings = array();
         foreach ($params['groupingids'] as $groupingid) {
@@ -799,7 +803,30 @@ class core_group_external extends external_api {
                 external_format_text($grouping->description, $grouping->descriptionformat,
                         $context->id, 'grouping', 'description', $grouping->id);
 
-            $groupings[] = (array)$grouping;
+            $groupingarray = (array)$grouping;
+
+            if ($params['returngroups']) {
+                $grouprecords = $DB->get_records_sql("SELECT * FROM {groups} g INNER JOIN {groupings_groups} gg ".
+                                               "ON g.id = gg.groupid WHERE gg.groupingid = ? ".
+                                               "ORDER BY groupid", array($groupingid));
+                if ($grouprecords) {
+                    $groups = array();
+                    foreach ($grouprecords as $grouprecord) {
+                        list($grouprecord->description, $grouprecord->descriptionformat) =
+                        external_format_text($grouprecord->description, $grouprecord->descriptionformat,
+                        $context->id, 'group', 'description', $grouprecord->groupid);
+                        $groups[] = array('id' => $grouprecord->groupid,
+                                          'name' => $grouprecord->name,
+                                          'description' => $grouprecord->description,
+                                          'descriptionformat' => $grouprecord->descriptionformat,
+                                          'enrolmentkey' => $grouprecord->enrolmentkey,
+                                          'courseid' => $grouprecord->courseid
+                                          );
+                    }
+                    $groupingarray['groups'] = $groups;
+                }
+            }
+            $groupings[] = $groupingarray;
         }
 
         return $groupings;
@@ -819,7 +846,19 @@ class core_group_external extends external_api {
                     'courseid' => new external_value(PARAM_INT, 'id of course'),
                     'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
                     'description' => new external_value(PARAM_RAW, 'grouping description text'),
-                    'descriptionformat' => new external_format_value('description')
+                    'descriptionformat' => new external_format_value('description'),
+                    'groups' => new external_multiple_structure(
+                        new external_single_structure(
+                            array(
+                                'id' => new external_value(PARAM_INT, 'group record id'),
+                                'courseid' => new external_value(PARAM_INT, 'id of course'),
+                                'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
+                                'description' => new external_value(PARAM_RAW, 'group description text'),
+                                'descriptionformat' => new external_format_value('description'),
+                                'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase')
+                            )
+                        ),
+                    'optional groups', VALUE_OPTIONAL)
                 )
             )
         );

diff --git a/group/tests/externallib_test.php b/group/tests/externallib_test.php
index 996d3c6..8048d18 100644 (file)
--- a/group/tests/externallib_test.php
+++ b/group/tests/externallib_test.php
@@ -30,6 +30,7 @@ global $CFG;
 
 require_once($CFG->dirroot . '/webservice/tests/helpers.php');
 require_once($CFG->dirroot . '/group/externallib.php');
+require_once($CFG->dirroot . '/group/lib.php');
 
 class core_group_external_testcase extends externallib_advanced_testcase {
 
@@ -207,4 +208,81 @@ class core_group_external_testcase extends externallib_advanced_testcase {
         $this->setExpectedException('required_capability_exception');
         $froups = core_group_external::delete_groups(array($group3->id));
     }
+
+    /**
+     * Test get_groupings
+     */
+    public function test_get_groupings() {
+        global $DB;
+
+        $this->resetAfterTest(true);
+
+        $course = self::getDataGenerator()->create_course();
+
+        $groupingdata = array();
+        $groupingdata['courseid'] = $course->id;
+        $groupingdata['name'] = 'Grouping Test';
+        $groupingdata['description'] = 'Grouping Test description';
+        $groupingdata['descriptionformat'] = FORMAT_MOODLE;
+
+        $grouping = self::getDataGenerator()->create_grouping($groupingdata);
+
+        // Set the required capabilities by the external function.
+        $context = context_course::instance($course->id);
+        $roleid = $this->assignUserCapability('moodle/course:managegroups', $context->id);
+        $this->assignUserCapability('moodle/course:view', $context->id, $roleid);
+
+        // Call the external function without specifying the optional parameter.
+        $groupings = core_group_external::get_groupings(array($grouping->id));
+        // We need to execute the return values cleaning process to simulate the web service server.
+        $groupings = external_api::clean_returnvalue(core_group_external::get_groupings_returns(), $groupings);
+
+        $this->assertEquals(1, count($groupings));
+
+        $group1data = array();
+        $group1data['courseid'] = $course->id;
+        $group1data['name'] = 'Group Test 1';
+        $group1data['description'] = 'Group Test 1 description';
+        $group1data['descriptionformat'] = FORMAT_MOODLE;
+        $group2data = array();
+        $group2data['courseid'] = $course->id;
+        $group2data['name'] = 'Group Test 2';
+        $group2data['description'] = 'Group Test 2 description';
+        $group2data['descriptionformat'] = FORMAT_MOODLE;
+
+        $group1 = self::getDataGenerator()->create_group($group1data);
+        $group2 = self::getDataGenerator()->create_group($group2data);
+
+        groups_assign_grouping($grouping->id, $group1->id);
+        groups_assign_grouping($grouping->id, $group2->id);
+
+        // Call the external function specifying that groups are returned.
+        $groupings = core_group_external::get_groupings(array($grouping->id), true);
+        // We need to execute the return values cleaning process to simulate the web service server.
+        $groupings = external_api::clean_returnvalue(core_group_external::get_groupings_returns(), $groupings);
+        $this->assertEquals(1, count($groupings));
+        $this->assertEquals(2, count($groupings[0]['groups']));
+        foreach ($groupings[0]['groups'] as $group) {
+            $dbgroup = $DB->get_record('groups', array('id' => $group['id']), '*', MUST_EXIST);
+            $dbgroupinggroups = $DB->get_record('groupings_groups',
+                                                array('groupingid' => $groupings[0]['id'],
+                                                      'groupid' => $group['id']),
+                                                '*', MUST_EXIST);
+            switch ($dbgroup->name) {
+                case $group1->name:
+                    $groupdescription = $group1->description;
+                    $groupcourseid = $group1->courseid;
+                    break;
+                case $group2->name:
+                    $groupdescription = $group2->description;
+                    $groupcourseid = $group2->courseid;
+                    break;
+                default:
+                    throw new moodle_exception('unknowgroupname');
+                    break;
+            }
+            $this->assertEquals($dbgroup->description, $groupdescription);
+            $this->assertEquals($dbgroup->courseid, $groupcourseid);
+        }
+    }
 }