diff --git a/lib/db/services.php b/lib/db/services.php index ae5b87d4db6..a558421d5fc 100644 --- a/lib/db/services.php +++ b/lib/db/services.php @@ -1222,6 +1222,7 @@ $services = array( 'mod_chat_view_chat', 'mod_chat_get_chats_by_courses', 'mod_book_view_book', + 'mod_book_get_books_by_courses', 'mod_choice_get_choice_results', 'mod_choice_get_choice_options', 'mod_choice_submit_choice_response', diff --git a/mod/book/classes/external.php b/mod/book/classes/external.php index 0ffa8cb3830..45b9e08ba23 100644 --- a/mod/book/classes/external.php +++ b/mod/book/classes/external.php @@ -149,4 +149,118 @@ class mod_book_external extends external_api { ); } + /** + * Describes the parameters for get_books_by_courses. + * + * @return external_external_function_parameters + * @since Moodle 3.0 + */ + public static function get_books_by_courses_parameters() { + return new external_function_parameters ( + array( + 'courseids' => new external_multiple_structure( + new external_value(PARAM_INT, 'course id'), 'Array of course ids', VALUE_DEFAULT, array() + ), + ) + ); + } + + /** + * Returns a list of books in a provided list of courses, + * if no list is provided all books that the user can view will be returned. + * + * @param array $courseids the course ids + * @return array of books details + * @since Moodle 3.0 + */ + public static function get_books_by_courses($courseids = array()) { + global $CFG; + + $returnedbooks = array(); + $warnings = array(); + + $params = self::validate_parameters(self::get_books_by_courses_parameters(), array('courseids' => $courseids)); + + if (empty($params['courseids'])) { + $params['courseids'] = array_keys(enrol_get_my_courses()); + } + + // Ensure there are courseids to loop through. + if (!empty($params['courseids'])) { + + list($courses, $warnings) = external_util::validate_courses($params['courseids']); + + // Get the books in this course, this function checks users visibility permissions. + // We can avoid then additional validate_context calls. + $books = get_all_instances_in_courses("book", $courses); + foreach ($books as $book) { + $context = context_module::instance($book->coursemodule); + // Entry to return. + $bookdetails = array(); + // First, we return information that any user can see in the web interface. + $bookdetails['id'] = $book->id; + $bookdetails['coursemodule'] = $book->coursemodule; + $bookdetails['course'] = $book->course; + $bookdetails['name'] = format_string($book->name, true, array('context' => $context)); + // Format intro. + list($bookdetails['intro'], $bookdetails['introformat']) = + external_format_text($book->intro, $book->introformat, $context->id, 'mod_book', 'intro', null); + $bookdetails['numbering'] = $book->numbering; + $bookdetails['navstyle'] = $book->navstyle; + $bookdetails['customtitles'] = $book->customtitles; + + if (has_capability('moodle/course:manageactivities', $context)) { + $bookdetails['revision'] = $book->revision; + $bookdetails['timecreated'] = $book->timecreated; + $bookdetails['timemodified'] = $book->timemodified; + $bookdetails['section'] = $book->section; + $bookdetails['visible'] = $book->visible; + $bookdetails['groupmode'] = $book->groupmode; + $bookdetails['groupingid'] = $book->groupingid; + } + $returnedbooks[] = $bookdetails; + } + } + $result = array(); + $result['books'] = $returnedbooks; + $result['warnings'] = $warnings; + return $result; + } + + /** + * Describes the get_books_by_courses return value. + * + * @return external_single_structure + * @since Moodle 3.0 + */ + public static function get_books_by_courses_returns() { + return new external_single_structure( + array( + 'books' => new external_multiple_structure( + new external_single_structure( + array( + 'id' => new external_value(PARAM_INT, 'Book id'), + 'coursemodule' => new external_value(PARAM_INT, 'Course module id'), + 'course' => new external_value(PARAM_INT, 'Course id'), + 'name' => new external_value(PARAM_TEXT, 'Book name'), + 'intro' => new external_value(PARAM_RAW, 'The Book intro'), + 'introformat' => new external_format_value('intro'), + 'numbering' => new external_value(PARAM_INT, 'Book numbering configuration'), + 'navstyle' => new external_value(PARAM_INT, 'Book navigation style configuration'), + 'customtitles' => new external_value(PARAM_INT, 'Book custom titles type'), + 'revision' => new external_value(PARAM_INT, 'Book revision', VALUE_OPTIONAL), + 'timecreated' => new external_value(PARAM_INT, 'Time of creation', VALUE_OPTIONAL), + 'timemodified' => new external_value(PARAM_INT, 'Time of last modification', VALUE_OPTIONAL), + 'section' => new external_value(PARAM_INT, 'Course section id', VALUE_OPTIONAL), + 'visible' => new external_value(PARAM_BOOL, 'Visible', VALUE_OPTIONAL), + 'groupmode' => new external_value(PARAM_INT, 'Group mode', VALUE_OPTIONAL), + 'groupingid' => new external_value(PARAM_INT, 'Group id', VALUE_OPTIONAL), + ), 'Books' + ) + ), + 'warnings' => new external_warnings(), + ) + ); + } + } diff --git a/mod/book/db/services.php b/mod/book/db/services.php index be081d6dcce..02522705251 100644 --- a/mod/book/db/services.php +++ b/mod/book/db/services.php @@ -36,4 +36,12 @@ $functions = array( 'capabilities' => 'mod/book:read' ), + 'mod_book_get_books_by_courses' => array( + 'classname' => 'mod_book_external', + 'methodname' => 'get_books_by_courses', + 'description' => 'Returns a list of book instances in a provided set of courses, + if no courses are provided then all the book instances the user has access to will be returned.', + 'type' => 'read', + 'capabilities' => '' + ) ); diff --git a/mod/book/tests/externallib_test.php b/mod/book/tests/externallib_test.php index ec7a607f0b1..74dfec876f2 100644 --- a/mod/book/tests/externallib_test.php +++ b/mod/book/tests/externallib_test.php @@ -132,4 +132,71 @@ class mod_book_external_testcase extends externallib_advanced_testcase { } } + + /** + * Test get_books_by_courses + */ + public function test_get_books_by_courses() { + global $DB, $USER; + $this->resetAfterTest(true); + $this->setAdminUser(); + $course1 = self::getDataGenerator()->create_course(); + $bookoptions1 = array( + 'course' => $course1->id, + 'name' => 'First Book' + ); + $book1 = self::getDataGenerator()->create_module('book', $bookoptions1); + $course2 = self::getDataGenerator()->create_course(); + $bookoptions2 = array( + 'course' => $course2->id, + 'name' => 'Second Book' + ); + $book2 = self::getDataGenerator()->create_module('book', $bookoptions2); + $student1 = $this->getDataGenerator()->create_user(); + $studentrole = $DB->get_record('role', array('shortname' => 'student')); + + // Enroll Student1 in Course1. + self::getDataGenerator()->enrol_user($student1->id, $course1->id, $studentrole->id); + $this->setUser($student1); + + $books = mod_book_external::get_books_by_courses(); + // We need to execute the return values cleaning process to simulate the web service server. + $books = external_api::clean_returnvalue(mod_book_external::get_books_by_courses_returns(), $books); + $this->assertCount(1, $books['books']); + $this->assertEquals('First Book', $books['books'][0]['name']); + // We see 9 fields. + $this->assertCount(9, $books['books'][0]); + + // As Student you cannot see some book properties like 'section'. + $this->assertFalse(isset($books['books'][0]['section'])); + + // Student1 is not enrolled in course2. The webservice will return a warning! + $books = mod_book_external::get_books_by_courses(array($course2->id)); + // We need to execute the return values cleaning process to simulate the web service server. + $books = external_api::clean_returnvalue(mod_book_external::get_books_by_courses_returns(), $books); + $this->assertCount(0, $books['books']); + $this->assertEquals(1, $books['warnings'][0]['warningcode']); + + // Now as admin. + $this->setAdminUser(); + // As Admin we can see this book. + $books = mod_book_external::get_books_by_courses(array($course2->id)); + // We need to execute the return values cleaning process to simulate the web service server. + $books = external_api::clean_returnvalue(mod_book_external::get_books_by_courses_returns(), $books); + + $this->assertCount(1, $books['books']); + $this->assertEquals('Second Book', $books['books'][0]['name']); + // We see 16 fields. + $this->assertCount(16, $books['books'][0]); + // As an Admin you can see some book properties like 'section'. + $this->assertEquals(0, $books['books'][0]['section']); + + // Enrol student in the second course. + self::getDataGenerator()->enrol_user($student1->id, $course2->id, $studentrole->id); + $this->setUser($student1); + $books = mod_book_external::get_books_by_courses(); + $books = external_api::clean_returnvalue(mod_book_external::get_books_by_courses_returns(), $books); + $this->assertCount(2, $books['books']); + + } } diff --git a/mod/book/version.php b/mod/book/version.php index 424459a2185..a49ea1aeac4 100644 --- a/mod/book/version.php +++ b/mod/book/version.php @@ -25,6 +25,6 @@ defined('MOODLE_INTERNAL') || die; $plugin->component = 'mod_book'; // Full name of the plugin (used for diagnostics) -$plugin->version = 2015051101; // The current module version (Date: YYYYMMDDXX) +$plugin->version = 2015051102; // The current module version (Date: YYYYMMDDXX) $plugin->requires = 2015050500; // Requires this Moodle version $plugin->cron = 0; // Period for cron to check this module (secs) diff --git a/version.php b/version.php index 0e4f4f08249..9bffb7bf15f 100644 --- a/version.php +++ b/version.php @@ -29,7 +29,7 @@ defined('MOODLE_INTERNAL') || die(); -$version = 2015092201.00; // YYYYMMDD = weekly release date of this DEV branch. +$version = 2015092202.00; // YYYYMMDD = weekly release date of this DEV branch. // RR = release increments - 00 in DEV branches. // .XX = incremental changes.