MDL-50013 mod_book: New WS mod_book_view_book
[moodle.git] / mod / book / classes / external.php
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/>.
17 /**
18  * Book external API
19  *
20  * @package    mod_book
21  * @category   external
22  * @copyright  2015 Juan Leyva <juan@moodle.com>
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  * @since      Moodle 3.0
25  */
27 defined('MOODLE_INTERNAL') || die;
29 require_once("$CFG->libdir/externallib.php");
31 /**
32  * Book external functions
33  *
34  * @package    mod_book
35  * @category   external
36  * @copyright  2015 Juan Leyva <juan@moodle.com>
37  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
38  * @since      Moodle 3.0
39  */
40 class mod_book_external extends external_api {
42     /**
43      * Returns description of method parameters
44      *
45      * @return external_function_parameters
46      * @since Moodle 3.0
47      */
48     public static function view_book_parameters() {
49         return new external_function_parameters(
50             array(
51                 'bookid' => new external_value(PARAM_INT, 'book instance id'),
52                 'chapterid' => new external_value(PARAM_INT, 'chapter id', VALUE_DEFAULT, 0)
53             )
54         );
55     }
57     /**
58      * Simulate the book/view.php web interface page: trigger events, completion, etc...
59      *
60      * @param int $bookid the book instance id
61      * @param int $chapterid the book chapter id
62      * @return array of warnings and status result
63      * @since Moodle 3.0
64      * @throws moodle_exception
65      */
66     public static function view_book($bookid, $chapterid = 0) {
67         global $DB, $CFG;
68         require_once($CFG->dirroot . "/mod/book/lib.php");
69         require_once($CFG->dirroot . "/mod/book/locallib.php");
71         $params = self::validate_parameters(self::view_book_parameters(),
72                                             array(
73                                                 'bookid' => $bookid,
74                                                 'chapterid' => $chapterid
75                                             ));
76         $bookid = $params['bookid'];
77         $chapterid = $params['chapterid'];
79         $warnings = array();
81         // Request and permission validation.
82         $book = $DB->get_record('book', array('id' => $bookid), '*', MUST_EXIST);
83         list($course, $cm) = get_course_and_cm_from_instance($book, 'book');
85         $context = context_module::instance($cm->id);
86         self::validate_context($context);
88         require_capability('mod/book:read', $context);
90         $chapters = book_preload_chapters($book);
91         $firstchapterid = 0;
92         $lastchapterid = 0;
94         foreach ($chapters as $ch) {
95             if ($ch->hidden) {
96                 continue;
97             }
98             if (!$firstchapterid) {
99                 $firstchapterid = $ch->id;
100             }
101             $lastchapterid = $ch->id;
102         }
104         if (!$chapterid) {
105             // Trigger the module viewed events since we are displaying the book.
106             book_view($book, null, false, $course, $cm, $context);
107             $chapterid = $firstchapterid;
108         }
110         // Check if book is empty (warning).
111         if (!$chapterid) {
112             $warnings[] = array(
113                 'item' => 'book',
114                 'itemid' => $book->id,
115                 'warningcode' => '1',
116                 'message' => get_string('nocontent', 'mod_book')
117             );
118         } else {
119             $chapter = $DB->get_record('book_chapters', array('id' => $chapterid, 'bookid' => $book->id));
120             $viewhidden = has_capability('mod/book:viewhiddenchapters', $context);
122             if (!$chapter or ($chapter->hidden and !$viewhidden)) {
123                 throw new moodle_exception('errorchapter', 'mod_book');
124             }
126             // Trigger the chapter viewed event.
127             $islastchapter = ($chapter->id == $lastchapterid) ? true : false;
128             book_view($book, $chapter, $islastchapter, $course, $cm, $context);
129         }
131         $result = array();
132         $result['status'] = true;
133         $result['warnings'] = $warnings;
134         return $result;
135     }
137     /**
138      * Returns description of method result value
139      *
140      * @return external_description
141      * @since Moodle 3.0
142      */
143     public static function view_book_returns() {
144         return new external_single_structure(
145             array(
146                 'status' => new external_value(PARAM_BOOL, 'status: true if success'),
147                 'warnings' => new external_warnings()
148             )
149         );
150     }