[Summary view]

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]

   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/>.
  16  
  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   */
  26  
  27  use core_course\external\helper_for_get_mods_by_courses;
  28  
  29  defined('MOODLE_INTERNAL') || die;
  30  
  31  require_once("$CFG->libdir/externallib.php");
  32  
  33  /**
  34   * Book external functions
  35   *
  36   * @package    mod_book
  37   * @category   external
  38   * @copyright  2015 Juan Leyva <juan@moodle.com>
  39   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  40   * @since      Moodle 3.0
  41   */
  42  class mod_book_external extends external_api {
  43  
  44      /**
  45       * Returns description of method parameters
  46       *
  47       * @return external_function_parameters
  48       * @since Moodle 3.0
  49       */
  50      public static function view_book_parameters() {
  51          return new external_function_parameters(
  52              array(
  53                  'bookid' => new external_value(PARAM_INT, 'book instance id'),
  54                  'chapterid' => new external_value(PARAM_INT, 'chapter id', VALUE_DEFAULT, 0)
  55              )
  56          );
  57      }
  58  
  59      /**
  60       * Simulate the book/view.php web interface page: trigger events, completion, etc...
  61       *
  62       * @param int $bookid the book instance id
  63       * @param int $chapterid the book chapter id
  64       * @return array of warnings and status result
  65       * @since Moodle 3.0
  66       * @throws moodle_exception
  67       */
  68      public static function view_book($bookid, $chapterid = 0) {
  69          global $DB, $CFG;
  70          require_once($CFG->dirroot . "/mod/book/lib.php");
  71          require_once($CFG->dirroot . "/mod/book/locallib.php");
  72  
  73          $params = self::validate_parameters(self::view_book_parameters(),
  74                                              array(
  75                                                  'bookid' => $bookid,
  76                                                  'chapterid' => $chapterid
  77                                              ));
  78          $bookid = $params['bookid'];
  79          $chapterid = $params['chapterid'];
  80  
  81          $warnings = array();
  82  
  83          // Request and permission validation.
  84          $book = $DB->get_record('book', array('id' => $bookid), '*', MUST_EXIST);
  85          list($course, $cm) = get_course_and_cm_from_instance($book, 'book');
  86  
  87          $context = context_module::instance($cm->id);
  88          self::validate_context($context);
  89  
  90          require_capability('mod/book:read', $context);
  91  
  92          $chapters = book_preload_chapters($book);
  93          $firstchapterid = 0;
  94  
  95          foreach ($chapters as $ch) {
  96              if ($ch->hidden) {
  97                  continue;
  98              }
  99              if (!$firstchapterid) {
 100                  $firstchapterid = $ch->id;
 101              }
 102          }
 103  
 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          }
 109  
 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);
 121  
 122              if (!$chapter or ($chapter->hidden and !$viewhidden)) {
 123                  throw new moodle_exception('errorchapter', 'mod_book');
 124              }
 125  
 126              // Trigger the chapter viewed event.
 127              book_view($book, $chapter, \mod_book\helper::is_last_visible_chapter($chapterid, $chapters), $course, $cm, $context);
 128          }
 129  
 130          $result = array();
 131          $result['status'] = true;
 132          $result['warnings'] = $warnings;
 133          return $result;
 134      }
 135  
 136      /**
 137       * Returns description of method result value
 138       *
 139       * @return external_description
 140       * @since Moodle 3.0
 141       */
 142      public static function view_book_returns() {
 143          return new external_single_structure(
 144              array(
 145                  'status' => new external_value(PARAM_BOOL, 'status: true if success'),
 146                  'warnings' => new external_warnings()
 147              )
 148          );
 149      }
 150  
 151      /**
 152       * Describes the parameters for get_books_by_courses.
 153       *
 154       * @return external_function_parameters
 155       * @since Moodle 3.0
 156       */
 157      public static function get_books_by_courses_parameters() {
 158          return new external_function_parameters (
 159              array(
 160                  'courseids' => new external_multiple_structure(
 161                      new external_value(PARAM_INT, 'course id'), 'Array of course ids', VALUE_DEFAULT, array()
 162                  ),
 163              )
 164          );
 165      }
 166  
 167      /**
 168       * Returns a list of books in a provided list of courses,
 169       * if no list is provided all books that the user can view will be returned.
 170       *
 171       * @param array $courseids the course ids
 172       * @return array of books details
 173       * @since Moodle 3.0
 174       */
 175      public static function get_books_by_courses($courseids = array()) {
 176  
 177          $returnedbooks = array();
 178          $warnings = array();
 179  
 180          $params = self::validate_parameters(self::get_books_by_courses_parameters(), array('courseids' => $courseids));
 181  
 182          $courses = array();
 183          if (empty($params['courseids'])) {
 184              $courses = enrol_get_my_courses();
 185              $params['courseids'] = array_keys($courses);
 186          }
 187  
 188          // Ensure there are courseids to loop through.
 189          if (!empty($params['courseids'])) {
 190  
 191              list($courses, $warnings) = external_util::validate_courses($params['courseids'], $courses);
 192  
 193              // Get the books in this course, this function checks users visibility permissions.
 194              // We can avoid then additional validate_context calls.
 195              $books = get_all_instances_in_courses("book", $courses);
 196              foreach ($books as $book) {
 197                  // Entry to return.
 198                  $bookdetails = helper_for_get_mods_by_courses::standard_coursemodule_element_values($book, 'mod_book');
 199                  $bookdetails['numbering']         = $book->numbering;
 200                  $bookdetails['navstyle']          = $book->navstyle;
 201                  $bookdetails['customtitles']      = $book->customtitles;
 202  
 203                  if (has_capability('moodle/course:manageactivities', context_module::instance($book->coursemodule))) {
 204                      $bookdetails['revision']      = $book->revision;
 205                      $bookdetails['timecreated']   = $book->timecreated;
 206                      $bookdetails['timemodified']  = $book->timemodified;
 207                  }
 208                  $returnedbooks[] = $bookdetails;
 209              }
 210          }
 211          $result = array();
 212          $result['books'] = $returnedbooks;
 213          $result['warnings'] = $warnings;
 214          return $result;
 215      }
 216  
 217      /**
 218       * Describes the get_books_by_courses return value.
 219       *
 220       * @return external_single_structure
 221       * @since Moodle 3.0
 222       */
 223      public static function get_books_by_courses_returns() {
 224          return new external_single_structure(
 225              array(
 226                  'books' => new external_multiple_structure(
 227                      new external_single_structure(array_merge(
 228                          helper_for_get_mods_by_courses::standard_coursemodule_elements_returns(),
 229                          [
 230                              'numbering' => new external_value(PARAM_INT, 'Book numbering configuration'),
 231                              'navstyle' => new external_value(PARAM_INT, 'Book navigation style configuration'),
 232                              'customtitles' => new external_value(PARAM_INT, 'Book custom titles type'),
 233                              'revision' => new external_value(PARAM_INT, 'Book revision', VALUE_OPTIONAL),
 234                              'timecreated' => new external_value(PARAM_INT, 'Time of creation', VALUE_OPTIONAL),
 235                              'timemodified' => new external_value(PARAM_INT, 'Time of last modification', VALUE_OPTIONAL),
 236                          ]
 237                      ), 'Books')
 238                  ),
 239                  'warnings' => new external_warnings(),
 240              )
 241          );
 242      }
 243  }