MDL-32709 book: coding style, deprecated and minor fixes
[moodle.git] / mod / book / lib.php
1 <?php
2 // This file is part of Book module for 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 module core interaction API
19  *
20  * @package    mod_book
21  * @copyright  2004-2011 Petr Skoda {@link http://skodak.org}
22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 defined('MOODLE_INTERNAL') || die;
27 /**
28  * Returns list of available numbering types
29  * @return array
30  */
31 function book_get_numbering_types() {
32     global $CFG; // required for the include
33     require_once(dirname(__FILE__).'/locallib.php');
35     return array (
36         BOOK_NUM_NONE       => get_string('numbering0', 'mod_book'),
37         BOOK_NUM_NUMBERS    => get_string('numbering1', 'mod_book'),
38         BOOK_NUM_BULLETS    => get_string('numbering2', 'mod_book'),
39         BOOK_NUM_INDENTED   => get_string('numbering3', 'mod_book')
40     );
41 }
43 /**
44  * Returns all other caps used in module
45  * @return array
46  */
47 function book_get_extra_capabilities() {
48     // used for group-members-only
49     return array('moodle/site:accessallgroups');
50 }
52 /**
53  * Add book instance.
54  *
55  * @param stdClass $data
56  * @param stdClass $mform
57  * @return int new book instance id
58  */
59 function book_add_instance($data, $mform) {
60     global $DB;
62     $data->timecreated = time();
63     $data->timemodified = $data->timecreated;
64     if (!isset($data->customtitles)) {
65         $data->customtitles = 0;
66     }
68     return $DB->insert_record('book', $data);
69 }
71 /**
72  * Update book instance.
73  *
74  * @param stdClass $data
75  * @param stdClass $mform
76  * @return bool true
77  */
78 function book_update_instance($data, $mform) {
79     global $DB;
81     $data->timemodified = time();
82     $data->id = $data->instance;
83     if (!isset($data->customtitles)) {
84         $data->customtitles = 0;
85     }
87     $DB->update_record('book', $data);
89     $book = $DB->get_record('book', array('id'=>$data->id));
90     $DB->set_field('book', 'revision', $book->revision+1, array('id'=>$book->id));
92     return true;
93 }
95 /**
96  * Delete book instance by activity id
97  *
98  * @param int $id
99  * @return bool success
100  */
101 function book_delete_instance($id) {
102     global $DB;
104     if (!$book = $DB->get_record('book', array('id'=>$id))) {
105         return false;
106     }
108     $DB->delete_records('book_chapters', array('bookid'=>$book->id));
109     $DB->delete_records('book', array('id'=>$book->id));
111     return true;
114 /**
115  * Return use outline
116  *
117  * @param stdClass $course
118  * @param stdClass $user
119  * @param stdClass $mod
120  * @param object $book
121  * @return object|null
122  */
123 function book_user_outline($course, $user, $mod, $book) {
124     global $DB;
126     if ($logs = $DB->get_records('log', array('userid'=>$user->id, 'module'=>'book',
127                                               'action'=>'view', 'info'=>$book->id), 'time ASC')) {
129         $numviews = count($logs);
130         $lastlog = array_pop($logs);
132         $result = new stdClass();
133         $result->info = get_string('numviews', '', $numviews);
134         $result->time = $lastlog->time;
136         return $result;
137     }
138     return null;
141 /**
142  * Print a detailed representation of what a  user has done with
143  * a given particular instance of this module, for user activity reports.
144  *
145  * @param stdClass $course
146  * @param stdClass $user
147  * @param stdClass $mod
148  * @param stdClass $book
149  * @return bool
150  */
151 function book_user_complete($course, $user, $mod, $book) {
152     return true;
155 /**
156  * Given a course and a time, this module should find recent activity
157  * that has occurred in book activities and print it out.
158  *
159  * @param stdClass $course
160  * @param bool $viewfullnames
161  * @param int $timestart
162  * @return bool true if there was output, or false is there was none
163  */
164 function book_print_recent_activity($course, $viewfullnames, $timestart) {
165     return false;  //  True if anything was printed, otherwise false
168 /**
169  * No cron in book.
170  *
171  * @return bool
172  */
173 function book_cron () {
174     return true;
177 /**
178  * No grading in book.
179  *
180  * @param int $bookid
181  * @return null
182  */
183 function book_grades($bookid) {
184     return null;
187 /**
188  * This function returns if a scale is being used by one book
189  * it it has support for grading and scales. Commented code should be
190  * modified if necessary. See book, glossary or journal modules
191  * as reference.
192  *
193  * @param int $bookid
194  * @param int $scaleid
195  * @return boolean True if the scale is used by any journal
196  */
197 function book_scale_used($bookid, $scaleid) {
198     return false;
201 /**
202  * Checks if scale is being used by any instance of book
203  *
204  * This is used to find out if scale used anywhere
205  *
206  * @param int $scaleid
207  * @return bool true if the scale is used by any book
208  */
209 function book_scale_used_anywhere($scaleid) {
210     return false;
213 /**
214  * Return read actions.
215  * @return array
216  */
217 function book_get_view_actions() {
218     global $CFG; // necessary for includes
220     $return = array('view', 'view all');
222     $plugins = get_plugin_list('booktool');
223     foreach ($plugins as $plugin => $dir) {
224         if (file_exists("$dir/lib.php")) {
225             require_once("$dir/lib.php");
226         }
227         $function = 'booktool_'.$plugin.'_get_view_actions';
228         if (function_exists($function)) {
229             if ($actions = $function()) {
230                 $return = array_merge($return, $actions);
231             }
232         }
233     }
235     return $return;
238 /**
239  * Return write actions.
240  * @return array
241  */
242 function book_get_post_actions() {
243     global $CFG; // necessary for includes
245     $return = array('update');
247     $plugins = get_plugin_list('booktool');
248     foreach ($plugins as $plugin => $dir) {
249         if (file_exists("$dir/lib.php")) {
250             require_once("$dir/lib.php");
251         }
252         $function = 'booktool_'.$plugin.'_get_post_actions';
253         if (function_exists($function)) {
254             if ($actions = $function()) {
255                 $return = array_merge($return, $actions);
256             }
257         }
258     }
260     return $return;
263 /**
264  * Supported features
265  *
266  * @param string $feature FEATURE_xx constant for requested feature
267  * @return mixed True if module supports feature, false if not, null if doesn't know
268  */
269 function book_supports($feature) {
270     switch($feature) {
271         case FEATURE_MOD_ARCHETYPE:           return MOD_ARCHETYPE_RESOURCE;
272         case FEATURE_GROUPS:                  return false;
273         case FEATURE_GROUPINGS:               return false;
274         case FEATURE_GROUPMEMBERSONLY:        return true;
275         case FEATURE_MOD_INTRO:               return true;
276         case FEATURE_COMPLETION_TRACKS_VIEWS: return true;
277         case FEATURE_GRADE_HAS_GRADE:         return false;
278         case FEATURE_GRADE_OUTCOMES:          return false;
279         case FEATURE_BACKUP_MOODLE2:          return true;
280         case FEATURE_SHOW_DESCRIPTION:        return true;
282         default: return null;
283     }
286 /**
287  * Adds module specific settings to the settings block
288  *
289  * @param settings_navigation $settingsnav The settings navigation object
290  * @param navigation_node $booknode The node to add module settings to
291  * @return void
292  */
293 function book_extend_settings_navigation(settings_navigation $settingsnav, navigation_node $booknode) {
294     global $USER, $PAGE, $CFG, $DB, $OUTPUT;
296     if ($PAGE->cm->modname !== 'book') {
297         return;
298     }
300     if (empty($PAGE->cm->context)) {
301         $PAGE->cm->context = get_context_instance(CONTEXT_MODULE, $PAGE->cm->instance);
302     }
304     $plugins = get_plugin_list('booktool');
305     foreach ($plugins as $plugin => $dir) {
306         if (file_exists("$dir/lib.php")) {
307             require_once("$dir/lib.php");
308         }
309         $function = 'booktool_'.$plugin.'_extend_settings_navigation';
310         if (function_exists($function)) {
311             $function($settingsnav, $booknode);
312         }
313     }
315     $params = $PAGE->url->params();
317     if (!empty($params['id']) and !empty($params['chapterid']) and has_capability('mod/book:edit', $PAGE->cm->context)) {
318         if (!empty($USER->editing)) {
319             $string = get_string("turneditingoff");
320             $edit = '0';
321         } else {
322             $string = get_string("turneditingon");
323             $edit = '1';
324         }
325         $url = new moodle_url('/mod/book/view.php', array('id'=>$params['id'], 'chapterid'=>$params['chapterid'], 'edit'=>$edit, 'sesskey'=>sesskey()));
326         $booknode->add($string, $url, navigation_node::TYPE_SETTING);
327     }
331 /**
332  * Lists all browsable file areas
333  * @param object $course
334  * @param object $cm
335  * @param object $context
336  * @return array
337  */
338 function book_get_file_areas($course, $cm, $context) {
339     $areas = array();
340     $areas['chapter'] = get_string('chapters', 'mod_book');
341     return $areas;
344 /**
345  * File browsing support for book module chapter area.
346  * @param object $browser
347  * @param object $areas
348  * @param object $course
349  * @param object $cm
350  * @param object $context
351  * @param string $filearea
352  * @param int $itemid
353  * @param string $filepath
354  * @param string $filename
355  * @return object file_info instance or null if not found
356  */
357 function book_get_file_info($browser, $areas, $course, $cm, $context, $filearea, $itemid, $filepath, $filename) {
358     global $CFG, $DB;
360     // note: 'intro' area is handled in file_browser automatically
362     if (!has_capability('mod/book:read', $context)) {
363         return null;
364     }
366     if ($filearea !== 'chapter') {
367         return null;
368     }
370     require_once(dirname(__FILE__).'/locallib.php');
372     if (is_null($itemid)) {
373         return new book_file_info($browser, $course, $cm, $context, $areas, $filearea);
374     }
376     $fs = get_file_storage();
377     $filepath = is_null($filepath) ? '/' : $filepath;
378     $filename = is_null($filename) ? '.' : $filename;
379     if (!$storedfile = $fs->get_file($context->id, 'mod_book', $filearea, $itemid, $filepath, $filename)) {
380         return null;
381     }
383     // modifications may be tricky - may cause caching problems
384     $canwrite = has_capability('mod/book:edit', $context);
386     $chaptername = $DB->get_field('book_chapters', 'title', array('bookid'=>$cm->instance, 'id'=>$itemid));
387     $chaptername = format_string($chaptername, true, array('context'=>$context));
389     $urlbase = $CFG->wwwroot.'/pluginfile.php';
390     return new file_info_stored($browser, $context, $storedfile, $urlbase, $chaptername, true, true, $canwrite, false);
393 /**
394  * Serves the book attachments. Implements needed access control ;-)
395  *
396  * @param stdClass $course course object
397  * @param cm_info $cm course module object
398  * @param context $context context object
399  * @param string $filearea file area
400  * @param array $args extra arguments
401  * @param bool $forcedownload whether or not force download
402  * @param array $options additional options affecting the file serving
403  * @return bool false if file not found, does not return if found - just send the file
404  */
405 function book_pluginfile($course, $cm, $context, $filearea, $args, $forcedownload, array $options=array()) {
406     global $DB;
408     if ($context->contextlevel != CONTEXT_MODULE) {
409         return false;
410     }
412     require_course_login($course, true, $cm);
414     if ($filearea !== 'chapter') {
415         return false;
416     }
418     if (!has_capability('mod/book:read', $context)) {
419         return false;
420     }
422     $chid = (int)array_shift($args);
424     if (!$book = $DB->get_record('book', array('id'=>$cm->instance))) {
425         return false;
426     }
428     if (!$chapter = $DB->get_record('book_chapters', array('id'=>$chid, 'bookid'=>$book->id))) {
429         return false;
430     }
432     if ($chapter->hidden and !has_capability('mod/book:viewhiddenchapters', $context)) {
433         return false;
434     }
436     $fs = get_file_storage();
437     $relativepath = implode('/', $args);
438     $fullpath = "/$context->id/mod_book/chapter/$chid/$relativepath";
439     if (!$file = $fs->get_file_by_hash(sha1($fullpath)) or $file->is_directory()) {
440         return false;
441     }
443     // finally send the file
444     send_stored_file($file, 360, 0, $forcedownload, $options);
447 /**
448  * Return a list of page types
449  *
450  * @param string $pagetype current page type
451  * @param stdClass $parentcontext Block's parent context
452  * @param stdClass $currentcontext Current context of block
453  * @return array
454  */
455 function book_page_type_list($pagetype, $parentcontext, $currentcontext) {
456     $module_pagetype = array('mod-book-*'=>get_string('page-mod-book-x', 'mod_book'));
457     return $module_pagetype;