diff --git a/lib/db/services.php b/lib/db/services.php index 8e4fc13462b..d1dbce6d416 100644 --- a/lib/db/services.php +++ b/lib/db/services.php @@ -1165,6 +1165,7 @@ $services = array( 'mod_chat_send_chat_message', 'mod_chat_get_chat_latest_messages', 'mod_chat_view_chat', + 'mod_book_view_book', ), 'enabled' => 0, 'restrictedusers' => 0, diff --git a/mod/book/classes/external.php b/mod/book/classes/external.php new file mode 100644 index 00000000000..0ffa8cb3830 --- /dev/null +++ b/mod/book/classes/external.php @@ -0,0 +1,152 @@ +. + +/** + * Book external API + * + * @package mod_book + * @category external + * @copyright 2015 Juan Leyva + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 3.0 + */ + +defined('MOODLE_INTERNAL') || die; + +require_once("$CFG->libdir/externallib.php"); + +/** + * Book external functions + * + * @package mod_book + * @category external + * @copyright 2015 Juan Leyva + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 3.0 + */ +class mod_book_external extends external_api { + + /** + * Returns description of method parameters + * + * @return external_function_parameters + * @since Moodle 3.0 + */ + public static function view_book_parameters() { + return new external_function_parameters( + array( + 'bookid' => new external_value(PARAM_INT, 'book instance id'), + 'chapterid' => new external_value(PARAM_INT, 'chapter id', VALUE_DEFAULT, 0) + ) + ); + } + + /** + * Simulate the book/view.php web interface page: trigger events, completion, etc... + * + * @param int $bookid the book instance id + * @param int $chapterid the book chapter id + * @return array of warnings and status result + * @since Moodle 3.0 + * @throws moodle_exception + */ + public static function view_book($bookid, $chapterid = 0) { + global $DB, $CFG; + require_once($CFG->dirroot . "/mod/book/lib.php"); + require_once($CFG->dirroot . "/mod/book/locallib.php"); + + $params = self::validate_parameters(self::view_book_parameters(), + array( + 'bookid' => $bookid, + 'chapterid' => $chapterid + )); + $bookid = $params['bookid']; + $chapterid = $params['chapterid']; + + $warnings = array(); + + // Request and permission validation. + $book = $DB->get_record('book', array('id' => $bookid), '*', MUST_EXIST); + list($course, $cm) = get_course_and_cm_from_instance($book, 'book'); + + $context = context_module::instance($cm->id); + self::validate_context($context); + + require_capability('mod/book:read', $context); + + $chapters = book_preload_chapters($book); + $firstchapterid = 0; + $lastchapterid = 0; + + foreach ($chapters as $ch) { + if ($ch->hidden) { + continue; + } + if (!$firstchapterid) { + $firstchapterid = $ch->id; + } + $lastchapterid = $ch->id; + } + + if (!$chapterid) { + // Trigger the module viewed events since we are displaying the book. + book_view($book, null, false, $course, $cm, $context); + $chapterid = $firstchapterid; + } + + // Check if book is empty (warning). + if (!$chapterid) { + $warnings[] = array( + 'item' => 'book', + 'itemid' => $book->id, + 'warningcode' => '1', + 'message' => get_string('nocontent', 'mod_book') + ); + } else { + $chapter = $DB->get_record('book_chapters', array('id' => $chapterid, 'bookid' => $book->id)); + $viewhidden = has_capability('mod/book:viewhiddenchapters', $context); + + if (!$chapter or ($chapter->hidden and !$viewhidden)) { + throw new moodle_exception('errorchapter', 'mod_book'); + } + + // Trigger the chapter viewed event. + $islastchapter = ($chapter->id == $lastchapterid) ? true : false; + book_view($book, $chapter, $islastchapter, $course, $cm, $context); + } + + $result = array(); + $result['status'] = true; + $result['warnings'] = $warnings; + return $result; + } + + /** + * Returns description of method result value + * + * @return external_description + * @since Moodle 3.0 + */ + public static function view_book_returns() { + return new external_single_structure( + array( + 'status' => new external_value(PARAM_BOOL, 'status: true if success'), + 'warnings' => new external_warnings() + ) + ); + } + +} diff --git a/mod/book/db/services.php b/mod/book/db/services.php new file mode 100644 index 00000000000..be081d6dcce --- /dev/null +++ b/mod/book/db/services.php @@ -0,0 +1,39 @@ +. + +/** + * Book external functions and service definitions. + * + * @package mod_book + * @category external + * @copyright 2015 Juan Leyva + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 3.0 + */ + +defined('MOODLE_INTERNAL') || die; + +$functions = array( + + 'mod_book_view_book' => array( + 'classname' => 'mod_book_external', + 'methodname' => 'view_book', + 'description' => 'Simulate the view.php web interface book: trigger events, completion, etc...', + 'type' => 'write', + 'capabilities' => 'mod/book:read' + ), + +); diff --git a/mod/book/lib.php b/mod/book/lib.php index 8c3f1f761d0..41dddfed4a5 100644 --- a/mod/book/lib.php +++ b/mod/book/lib.php @@ -597,4 +597,32 @@ function book_export_contents($cm, $baseurl) { array_unshift($contents, $structurefile); return $contents; -} \ No newline at end of file +} + +/** + * Mark the activity completed (if required) and trigger the course_module_viewed event. + * + * @param stdClass $book book object + * @param stdClass $chapter chapter object + * @param bool $islaschapter is the las chapter of the book? + * @param stdClass $course course object + * @param stdClass $cm course module object + * @param stdClass $context context object + * @since Moodle 3.0 + */ +function book_view($book, $chapter, $islastchapter, $course, $cm, $context) { + + // First case, we are just opening the book. + if (empty($chapter)) { + \mod_book\event\course_module_viewed::create_from_book($book, $context)->trigger(); + + } else { + \mod_book\event\chapter_viewed::create_from_chapter($book, $context, $chapter)->trigger(); + + if ($islastchapter) { + // We cheat a bit here in assuming that viewing the last page means the user viewed the whole book. + $completion = new completion_info($course); + $completion->set_module_viewed($cm); + } + } +} diff --git a/mod/book/tests/externallib_test.php b/mod/book/tests/externallib_test.php new file mode 100644 index 00000000000..ec7a607f0b1 --- /dev/null +++ b/mod/book/tests/externallib_test.php @@ -0,0 +1,135 @@ +. + +/** + * External mod_book functions unit tests + * + * @package mod_book + * @category external + * @copyright 2015 Juan Leyva + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 3.0 + */ + +defined('MOODLE_INTERNAL') || die(); + +global $CFG; + +require_once($CFG->dirroot . '/webservice/tests/helpers.php'); + +/** + * External mod_book functions unit tests + * + * @package mod_book + * @category external + * @copyright 2015 Juan Leyva + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @since Moodle 3.0 + */ +class mod_book_external_testcase extends externallib_advanced_testcase { + + /** + * Test view_book + */ + public function test_view_book() { + global $DB; + + $this->resetAfterTest(true); + + $this->setAdminUser(); + // Setup test data. + $course = $this->getDataGenerator()->create_course(); + $book = $this->getDataGenerator()->create_module('book', array('course' => $course->id)); + $bookgenerator = $this->getDataGenerator()->get_plugin_generator('mod_book'); + $chapter = $bookgenerator->create_chapter(array('bookid' => $book->id)); + $chapterhidden = $bookgenerator->create_chapter(array('bookid' => $book->id, 'hidden' => 1)); + + $context = context_module::instance($book->cmid); + $cm = get_coursemodule_from_instance('book', $book->id); + + // Test invalid instance id. + try { + mod_book_external::view_book(0); + $this->fail('Exception expected due to invalid mod_book instance id.'); + } catch (moodle_exception $e) { + $this->assertEquals('invalidrecord', $e->errorcode); + } + + // Test not-enrolled user. + $user = self::getDataGenerator()->create_user(); + $this->setUser($user); + try { + mod_book_external::view_book($book->id, 0); + $this->fail('Exception expected due to not enrolled user.'); + } catch (moodle_exception $e) { + $this->assertEquals('requireloginerror', $e->errorcode); + } + + // Test user with full capabilities. + $studentrole = $DB->get_record('role', array('shortname' => 'student')); + $this->getDataGenerator()->enrol_user($user->id, $course->id, $studentrole->id); + + // Trigger and capture the event. + $sink = $this->redirectEvents(); + + $result = mod_book_external::view_book($book->id, 0); + $result = external_api::clean_returnvalue(mod_book_external::view_book_returns(), $result); + + $events = $sink->get_events(); + $this->assertCount(2, $events); + $event = array_shift($events); + + // Checking that the event contains the expected values. + $this->assertInstanceOf('\mod_book\event\course_module_viewed', $event); + $this->assertEquals($context, $event->get_context()); + $moodleurl = new \moodle_url('/mod/book/view.php', array('id' => $cm->id)); + $this->assertEquals($moodleurl, $event->get_url()); + $this->assertEventContextNotUsed($event); + $this->assertNotEmpty($event->get_name()); + + $event = array_shift($events); + $this->assertInstanceOf('\mod_book\event\chapter_viewed', $event); + $this->assertEquals($chapter->id, $event->objectid); + + $result = mod_book_external::view_book($book->id, $chapter->id); + $result = external_api::clean_returnvalue(mod_book_external::view_book_returns(), $result); + + $events = $sink->get_events(); + // We expect a total of 3 events. + $this->assertCount(3, $events); + + // Try to view a hidden chapter. + try { + mod_book_external::view_book($book->id, $chapterhidden->id); + $this->fail('Exception expected due to missing capability.'); + } catch (moodle_exception $e) { + $this->assertEquals('errorchapter', $e->errorcode); + } + + // Test user with no capabilities. + // We need a explicit prohibit since this capability is only defined in authenticated user and guest roles. + assign_capability('mod/book:read', CAP_PROHIBIT, $studentrole->id, $context->id); + accesslib_clear_all_caches_for_unit_testing(); + + try { + mod_book_external::view_book($book->id, 0); + $this->fail('Exception expected due to missing capability.'); + } catch (moodle_exception $e) { + $this->assertEquals('nopermissions', $e->errorcode); + } + + } +} diff --git a/mod/book/tests/lib_test.php b/mod/book/tests/lib_test.php index 351bf20d223..53a358c8b35 100644 --- a/mod/book/tests/lib_test.php +++ b/mod/book/tests/lib_test.php @@ -83,4 +83,57 @@ class mod_book_lib_testcase extends advanced_testcase { $this->assertEquals(json_encode(array()), $contents[0]['content']); } + + /** + * Test book_view + * @return void + */ + public function test_book_view() { + global $CFG, $DB; + + $CFG->enablecompletion = 1; + $this->resetAfterTest(); + + $this->setAdminUser(); + // Setup test data. + $course = $this->getDataGenerator()->create_course(array('enablecompletion' => 1)); + $book = $this->getDataGenerator()->create_module('book', array('course' => $course->id), + array('completion' => 2, 'completionview' => 1)); + $bookgenerator = $this->getDataGenerator()->get_plugin_generator('mod_book'); + $chapter = $bookgenerator->create_chapter(array('bookid' => $book->id)); + + $context = context_module::instance($book->cmid); + $cm = get_coursemodule_from_instance('book', $book->id); + + // Trigger and capture the event. + $sink = $this->redirectEvents(); + + // Check just opening the book. + book_view($book, 0, false, $course, $cm, $context); + + $events = $sink->get_events(); + $this->assertCount(1, $events); + $event = array_shift($events); + + // Checking that the event contains the expected values. + $this->assertInstanceOf('\mod_book\event\course_module_viewed', $event); + $this->assertEquals($context, $event->get_context()); + $moodleurl = new \moodle_url('/mod/book/view.php', array('id' => $cm->id)); + $this->assertEquals($moodleurl, $event->get_url()); + $this->assertEventContextNotUsed($event); + $this->assertNotEmpty($event->get_name()); + + // Check viewing one book chapter (the only one so it will be the first and last). + book_view($book, $chapter, true, $course, $cm, $context); + + $events = $sink->get_events(); + // We expect a total of 4 events. One for module viewed, one for chapter viewed and two belonging to completion. + $this->assertCount(4, $events); + + // Check completion status. + $completion = new completion_info($course); + $completiondata = $completion->get_data($cm); + $this->assertEquals(1, $completiondata->completionstate); + + } } diff --git a/mod/book/version.php b/mod/book/version.php index 0d13c501c39..424459a2185 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 = 2015051100; // The current module version (Date: YYYYMMDDXX) +$plugin->version = 2015051101; // 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/mod/book/view.php b/mod/book/view.php index f2a6398877c..0340fd6d174 100644 --- a/mod/book/view.php +++ b/mod/book/view.php @@ -23,6 +23,7 @@ */ require(dirname(__FILE__).'/../../config.php'); +require_once(dirname(__FILE__).'/lib.php'); require_once(dirname(__FILE__).'/locallib.php'); require_once($CFG->libdir.'/completionlib.php'); @@ -75,7 +76,8 @@ if ($allowedit and !$chapters) { } // Check chapterid and read chapter data if ($chapterid == '0') { // Go to first chapter if no given. - \mod_book\event\course_module_viewed::create_from_book($book, $context)->trigger(); + // Trigger course module viewed event. + book_view($book, null, false, $course, $cm, $context); foreach ($chapters as $ch) { if ($edit) { @@ -109,10 +111,6 @@ unset($id); unset($bid); unset($chapterid); -// Security checks END. - -\mod_book\event\chapter_viewed::create_from_chapter($book, $context, $chapter)->trigger(); - // Read standard strings. $strbooks = get_string('modulenameplural', 'mod_book'); $strbook = get_string('modulename', 'mod_book'); @@ -147,7 +145,7 @@ foreach ($chapters as $ch) { $last = $ch->id; } - +$islastchapter = false; if ($book->navstyle) { $navprevicon = right_to_left() ? 'nav_next' : 'nav_prev'; $navnexticon = right_to_left() ? 'nav_prev' : 'nav_next'; @@ -195,12 +193,12 @@ if ($book->navstyle) { '' . $navexit . ' ' . $OUTPUT->uarrow() . ''; } - // We cheat a bit here in assuming that viewing the last page means the user viewed the whole book. - $completion = new completion_info($course); - $completion->set_module_viewed($cm); + $islastchapter = true; } } +book_view($book, $chapter, $islastchapter, $course, $cm, $context); + // ===================================================== // Book display HTML code // ===================================================== diff --git a/version.php b/version.php index 9441797837b..34f1ac75cb2 100644 --- a/version.php +++ b/version.php @@ -29,7 +29,7 @@ defined('MOODLE_INTERNAL') || die(); -$version = 2015090802.00; // YYYYMMDD = weekly release date of this DEV branch. +$version = 2015090803.00; // YYYYMMDD = weekly release date of this DEV branch. // RR = release increments - 00 in DEV branches. // .XX = incremental changes.