From efb7a0a9b03bc3b0f7e92e0a3248d212fd1ac2b2 Mon Sep 17 00:00:00 2001
From: Frederic Massart <fred@moodle.com>
Date: Mon, 12 Oct 2015 17:42:34 +0800
Subject: [PATCH] MDL-49231 mod_glossary: External function get_categories

---
 mod/glossary/classes/external.php    | 78 ++++++++++++++++++++++++++++
 mod/glossary/tests/external_test.php | 30 +++++++++++
 2 files changed, 108 insertions(+)

diff --git a/mod/glossary/classes/external.php b/mod/glossary/classes/external.php
index 4e5f9116805..e211cd55dd4 100644
--- a/mod/glossary/classes/external.php
+++ b/mod/glossary/classes/external.php
@@ -662,4 +662,82 @@ class mod_glossary_external extends external_api {
         ));
     }
 
+    /**
+     * Returns the description of the external function parameters.
+     *
+     * @return external_function_parameters
+     * @since Moodle 3.1
+     */
+    public static function get_categories_parameters() {
+        return new external_function_parameters(array(
+            'id' => new external_value(PARAM_INT, 'Glossary entry ID'),
+            'from' => new external_value(PARAM_INT, 'Start returning records from here', VALUE_DEFAULT, 0),
+            'limit' => new external_value(PARAM_INT, 'Number of records to return', VALUE_DEFAULT, 20)
+        ));
+    }
+
+    /**
+     * Get the categories of a glossary.
+     *
+     * @param int $id The glossary ID.
+     * @param int $from Start returning records from here.
+     * @param int $limit Number of records to return.
+     * @return array of warnings and status result
+     * @since Moodle 3.1
+     * @throws moodle_exception
+     */
+    public static function get_categories($id, $from = 0, $limit = 20) {
+        global $DB;
+
+        $params = self::validate_parameters(self::get_categories_parameters(), array(
+            'id' => $id,
+            'from' => $from,
+            'limit' => $limit
+        ));
+        $id = $params['id'];
+        $from = $params['from'];
+        $limit = $params['limit'];
+        $warnings = array();
+
+        // Fetch and confirm.
+        $glossary = $DB->get_record('glossary', array('id' => $id), '*', MUST_EXIST);
+        list($course, $cm) = get_course_and_cm_from_instance($glossary, 'glossary');
+        $context = context_module::instance($cm->id);
+        self::validate_context($context);
+
+        // Fetch the categories.
+        $count = $DB->count_records('glossary_categories', array('glossaryid' => $id));
+        $categories = $DB->get_records('glossary_categories', array('glossaryid' => $id), 'name ASC', '*', $from, $limit);
+        foreach ($categories as $category) {
+            $category->name = external_format_string($category->name, $context->id);
+        }
+
+        return array(
+            'count' => $count,
+            'categories' => $categories,
+            'warnings' => array(),
+        );
+    }
+
+    /**
+     * Returns the description of the external function return value.
+     *
+     * @return external_description
+     * @since Moodle 3.1
+     */
+    public static function get_categories_returns() {
+        return new external_single_structure(array(
+            'count' => new external_value(PARAM_INT, 'The total number of records.'),
+            'categories' => new external_multiple_structure(
+                new external_single_structure(array(
+                    'id' => new external_value(PARAM_INT, 'The category ID'),
+                    'glossaryid' => new external_value(PARAM_INT, 'The glossary ID'),
+                    'name' => new external_value(PARAM_RAW, 'The name of the category'),
+                    'usedynalink' => new external_value(PARAM_BOOL, 'Whether the category is automatically linked'),
+                ))
+            ),
+            'warnings' => new external_warnings()
+        ));
+    }
+
 }
diff --git a/mod/glossary/tests/external_test.php b/mod/glossary/tests/external_test.php
index c52af0b6dc7..29e55fec4ce 100644
--- a/mod/glossary/tests/external_test.php
+++ b/mod/glossary/tests/external_test.php
@@ -374,4 +374,34 @@ class mod_glossary_external_testcase extends externallib_advanced_testcase {
         $this->assertEquals($e1d->id, $return['entries'][0]['id']);
         $this->assertEquals($e1b->id, $return['entries'][1]['id']);
     }
+
+    public function test_get_categories() {
+        $this->resetAfterTest(true);
+        $this->setAdminUser();
+
+        $gg = $this->getDataGenerator()->get_plugin_generator('mod_glossary');
+        $c1 = $this->getDataGenerator()->create_course();
+        $g1 = $this->getDataGenerator()->create_module('glossary', array('course' => $c1->id));
+        $g2 = $this->getDataGenerator()->create_module('glossary', array('course' => $c1->id));
+        $cat1a = $gg->create_category($g1);
+        $cat1b = $gg->create_category($g1);
+        $cat1c = $gg->create_category($g1);
+        $cat2a = $gg->create_category($g2);
+
+        $return = mod_glossary_external::get_categories($g1->id, 0, 20);
+        $return = external_api::clean_returnvalue(mod_glossary_external::get_categories_returns(), $return);
+        $this->assertCount(3, $return['categories']);
+        $this->assertEquals(3, $return['count']);
+        $this->assertEquals($cat1a->id, $return['categories'][0]['id']);
+        $this->assertEquals($cat1b->id, $return['categories'][1]['id']);
+        $this->assertEquals($cat1c->id, $return['categories'][2]['id']);
+
+        $return = mod_glossary_external::get_categories($g1->id, 1, 2);
+        $return = external_api::clean_returnvalue(mod_glossary_external::get_categories_returns(), $return);
+        $this->assertCount(2, $return['categories']);
+        $this->assertEquals(3, $return['count']);
+        $this->assertEquals($cat1b->id, $return['categories'][0]['id']);
+        $this->assertEquals($cat1c->id, $return['categories'][1]['id']);
+    }
+
 }