7f9a3d61bf1388501aa9a04ecf12052ca099cb97
[moodle.git] / mod / wiki / lib.php
1 <?php
3 // This file is part of Moodle - http://moodle.org/
4 //
5 // Moodle is free software: you can redistribute it and/or modify
6 // it under the terms of the GNU General Public License as published by
7 // the Free Software Foundation, either version 3 of the License, or
8 // (at your option) any later version.
9 //
10 // Moodle is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 // GNU General Public License for more details.
14 //
15 // You should have received a copy of the GNU General Public License
16 // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
18 /**
19  * Library of functions and constants for module wiki
20  *
21  * It contains the great majority of functions defined by Moodle
22  * that are mandatory to develop a module.
23  *
24  * @package mod-wiki-2.0
25  * @copyrigth 2009 Marc Alier, Jordi Piguillem marc.alier@upc.edu
26  * @copyrigth 2009 Universitat Politecnica de Catalunya http://www.upc.edu
27  *
28  * @author Jordi Piguillem
29  * @author Marc Alier
30  * @author David Jimenez
31  * @author Josep Arus
32  * @author Kenneth Riba
33  *
34  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
35  */
37 /**
38  * Given an object containing all the necessary data,
39  * (defined by the form in mod.html) this function
40  * will create a new instance and return the id number
41  * of the new instance.
42  *
43  * @param object $instance An object from the form in mod.html
44  * @return int The id of the newly inserted wiki record
45  **/
46 function wiki_add_instance($wiki) {
47     global $DB;
49     $wiki->timemodified = time();
50     # May have to add extra stuff in here #
51     if (empty($wiki->forceformat)) {
52         $wiki->forceformat = 0;
53     }
54     return $DB->insert_record('wiki', $wiki);
55 }
57 /**
58  * Given an object containing all the necessary data,
59  * (defined by the form in mod.html) this function
60  * will update an existing instance with new data.
61  *
62  * @param object $instance An object from the form in mod.html
63  * @return boolean Success/Fail
64  **/
65 function wiki_update_instance($wiki) {
66     global $DB;
68     $wiki->timemodified = time();
69     $wiki->id = $wiki->instance;
70     if (empty($wiki->forceformat)) {
71         $wiki->forceformat = 0;
72     }
74     # May have to add extra stuff in here #
76     return $DB->update_record('wiki', $wiki);
77 }
79 /**
80  * Given an ID of an instance of this module,
81  * this function will permanently delete the instance
82  * and any data that depends on it.
83  *
84  * @param int $id Id of the module instance
85  * @return boolean Success/Failure
86  **/
87 function wiki_delete_instance($id) {
88     global $DB;
90     if (!$wiki = $DB->get_record('wiki', array('id' => $id))) {
91         return false;
92     }
94     $result = true;
96     # Get subwiki information #
97     $subwikis = $DB->get_records('wiki_subwikis', array('wikiid' => $wiki->id));
99     foreach ($subwikis as $subwiki) {
100         # Get existing links, and delete them #
101         if (!$DB->delete_records('wiki_links', array('subwikiid' => $subwiki->id), IGNORE_MISSING)) {
102             $result = false;
103         }
105         # Get existing pages #
106         if ($pages = $DB->get_records('wiki_pages', array('subwikiid' => $subwiki->id))) {
107             foreach ($pages as $page) {
108                 # Get locks, and delete them #
109                 if (!$DB->delete_records('wiki_locks', array('pageid' => $page->id), IGNORE_MISSING)) {
110                     $result = false;
111                 }
113                 # Get versions, and delete them #
114                 if (!$DB->delete_records('wiki_versions', array('pageid' => $page->id), IGNORE_MISSING)) {
115                     $result = false;
116                 }
117             }
119             # Delete pages #
120             if (!$DB->delete_records('wiki_pages', array('subwikiid' => $subwiki->id), IGNORE_MISSING)) {
121                 $result = false;
122             }
123         }
125         # Get existing synonyms, and delete them #
126         if (!$DB->delete_records('wiki_synonyms', array('subwikiid' => $subwiki->id), IGNORE_MISSING)) {
127             $result = false;
128         }
130         # Delete any subwikis #
131         if (!$DB->delete_records('wiki_subwikis', array('id' => $subwiki->id), IGNORE_MISSING)) {
132             $result = false;
133         }
134     }
136     # Delete any dependent records here #
137     if (!$DB->delete_records('wiki', array('id' => $wiki->id))) {
138         $result = false;
139     }
141     return $result;
144 function wiki_reset_userdata($data) {
145     global $CFG,$DB;
146     require_once($CFG->dirroot . '/mod/wiki/pagelib.php');
147     require_once($CFG->dirroot . '/tag/lib.php');
149     $componentstr = get_string('modulenameplural', 'wiki');
150     $status = array();
152     //get the wiki(s) in this course.
153     if (!$wikis = $DB->get_records('wiki', array('course' => $data->courseid))) {
154         return false;
155     }
156     $errors = false;
157     foreach ($wikis as $wiki) {
159         // remove all comments
160         if (!empty($data->reset_wiki_comments)) {
161             if (!$cm = get_coursemodule_from_instance('wiki', $wiki->id)) {
162                 continue;
163             }
164             $context = get_context_instance(CONTEXT_MODULE, $cm->id);
165             $DB->delete_records_select('comments', "contextid = ? AND commentarea='wiki_page'", array($context->id));
166             $status[] = array('component'=>$componentstr, 'item'=>get_string('deleteallcomments'), 'error'=>false);
167         }
169         if (!empty($data->reset_wiki_tags)) {
170             # Get subwiki information #
171             $subwikis = $DB->get_records('wiki_subwikis', array('wikiid' => $wiki->id));
173             foreach ($subwikis as $subwiki) {
174                 if ($pages = $DB->get_records('wiki_pages', array('subwikiid' => $subwiki->id))) {
175                     foreach ($pages as $page) {
176                         $tags = tag_get_tags_array('wiki_pages', $page->id);
177                         foreach ($tags as $tagid => $tagname) {
178                             // Delete the related tag_instances related to the wiki page.
179                             $errors = tag_delete_instance('wiki_pages', $page->id, $tagid);
180                             $status[] = array('component' => $componentstr, 'item' => get_string('tagsdeleted', 'wiki'), 'error' => $errors);
181                         }
182                     }
183                 }
184             }
185         }
186     }
187     return $status;
191 function wiki_reset_course_form_definition(&$mform) {
192     $mform->addElement('header', 'wikiheader', get_string('modulenameplural', 'wiki'));
193     $mform->addElement('advcheckbox', 'reset_wiki_tags', get_string('removeallwikitags', 'wiki'));
194     $mform->addElement('advcheckbox', 'reset_wiki_comments', get_string('deleteallcomments'));
197 /**
198  * Return a small object with summary information about what a
199  * user has done with a given particular instance of this module
200  * Used for user activity reports.
201  * $return->time = the time they did it
202  * $return->info = a short text description
203  *
204  * @return null
205  * @todo Finish documenting this function
206  **/
207 function wiki_user_outline($course, $user, $mod, $wiki) {
208     $return = NULL;
209     return $return;
212 /**
213  * Print a detailed representation of what a user has done with
214  * a given particular instance of this module, for user activity reports.
215  *
216  * @return boolean
217  * @todo Finish documenting this function
218  **/
219 function wiki_user_complete($course, $user, $mod, $wiki) {
220     return true;
223 /**
224  * Indicates API features that the wiki supports.
225  *
226  * @uses FEATURE_GROUPS
227  * @uses FEATURE_GROUPINGS
228  * @uses FEATURE_GROUPMEMBERSONLY
229  * @uses FEATURE_MOD_INTRO
230  * @uses FEATURE_COMPLETION_TRACKS_VIEWS
231  * @uses FEATURE_COMPLETION_HAS_RULES
232  * @uses FEATURE_GRADE_HAS_GRADE
233  * @uses FEATURE_GRADE_OUTCOMES
234  * @param string $feature
235  * @return mixed True if yes (some features may use other values)
236  */
237 function wiki_supports($feature) {
238     switch ($feature) {
239     case FEATURE_GROUPS:
240         return true;
241     case FEATURE_GROUPINGS:
242         return true;
243     case FEATURE_GROUPMEMBERSONLY:
244         return true;
245     case FEATURE_MOD_INTRO:
246         return true;
247     case FEATURE_COMPLETION_TRACKS_VIEWS:
248         return true;
249     case FEATURE_COMPLETION_HAS_RULES:
250         return true;
251     case FEATURE_GRADE_HAS_GRADE:
252         return false;
253     case FEATURE_GRADE_OUTCOMES:
254         return false;
255     case FEATURE_RATE:
256         return false;
257     case FEATURE_BACKUP_MOODLE2:
258         return true;
260     default:
261         return null;
262     }
265 /**
266  * Given a course and a time, this module should find recent activity
267  * that has occurred in wiki activities and print it out.
268  * Return true if there was output, or false is there was none.
269  *
270  * @global $CFG
271  * @global $DB
272  * @uses CONTEXT_MODULE
273  * @uses VISIBLEGROUPS
274  * @param object $course
275  * @param bool $viewfullnames capability
276  * @param int $timestart
277  * @return boolean
278  **/
279 function wiki_print_recent_activity($course, $viewfullnames, $timestart) {
280     global $CFG, $DB, $OUTPUT;
282     $sql = "SELECT p.*, w.id as wikiid, sw.groupid
283             FROM {wiki_pages} p
284                 JOIN {wiki_subwikis} sw ON sw.id = p.subwikiid
285                 JOIN {wiki} w ON w.id = sw.wikiid
286             WHERE p.timemodified > ? AND w.course = ?
287             ORDER BY p.timemodified ASC";
288     if (!$pages = $DB->get_records_sql($sql, array($timestart, $course->id))) {
289         return false;
290     }
291     $modinfo =& get_fast_modinfo($course);
293     $wikis = array();
295     $modinfo = get_fast_modinfo($course);
297     foreach ($pages as $page) {
298         if (!isset($modinfo->instances['wiki'][$page->wikiid])) {
299             // not visible
300             continue;
301         }
302         $cm = $modinfo->instances['wiki'][$page->wikiid];
303         if (!$cm->uservisible) {
304             continue;
305         }
306         $context = get_context_instance(CONTEXT_MODULE, $cm->id);
308         if (!has_capability('mod/wiki:viewpage', $context)) {
309             continue;
310         }
312         $groupmode = groups_get_activity_groupmode($cm, $course);
314         if ($groupmode) {
315             if ($groupmode == SEPARATEGROUPS and !has_capability('mod/wiki:managewiki', $context)) {
316                 // separate mode
317                 if (isguestuser()) {
318                     // shortcut
319                     continue;
320                 }
322                 if (is_null($modinfo->groups)) {
323                     $modinfo->groups = groups_get_user_groups($course->id); // load all my groups and cache it in modinfo
324                     }
326                 if (!in_array($page->groupid, $modinfo->groups[0])) {
327                     continue;
328                 }
329             }
330         }
331         $wikis[] = $page;
332     }
333     unset($pages);
335     if (!$wikis) {
336         return false;
337     }
338     echo $OUTPUT->heading(get_string("updatedwikipages", 'wiki') . ':', 3);
339     foreach ($wikis as $wiki) {
340         $cm = $modinfo->instances['wiki'][$wiki->wikiid];
341         $link = $CFG->wwwroot . '/mod/wiki/view.php?pageid=' . $wiki->id;
342         print_recent_activity_note($wiki->timemodified, $wiki, $cm->name, $link, false, $viewfullnames);
343     }
345     return true; //  True if anything was printed, otherwise false
347 /**
348  * Function to be run periodically according to the moodle cron
349  * This function searches for things that need to be done, such
350  * as sending out mail, toggling flags etc ...
351  *
352  * @uses $CFG
353  * @return boolean
354  * @todo Finish documenting this function
355  **/
356 function wiki_cron() {
357     global $CFG;
359     return true;
362 /**
363  * Must return an array of grades for a given instance of this module,
364  * indexed by user.  It also returns a maximum allowed grade.
365  *
366  * Example:
367  *    $return->grades = array of grades;
368  *    $return->maxgrade = maximum allowed grade;
369  *
370  *    return $return;
371  *
372  * @param int $wikiid ID of an instance of this module
373  * @return mixed Null or object with an array of grades and with the maximum grade
374  **/
375 function wiki_grades($wikiid) {
376     return null;
379 /**
380  * Must return an array of user records (all data) who are participants
381  * for a given instance of wiki. Must include every user involved
382  * in the instance, independient of his role (student, teacher, admin...)
383  * See other modules as example.
384  *
385  * @todo: deprecated - to be deleted in 2.2
386  *
387  * @param int $wikiid ID of an instance of this module
388  * @return mixed boolean/array of students
389  **/
390 function wiki_get_participants($wikiid) {
391     return false;
394 /**
395  * This function returns if a scale is being used by one wiki
396  * it it has support for grading and scales. Commented code should be
397  * modified if necessary. See forum, glossary or journal modules
398  * as reference.
399  *
400  * @param int $wikiid ID of an instance of this module
401  * @return mixed
402  * @todo Finish documenting this function
403  **/
404 function wiki_scale_used($wikiid, $scaleid) {
405     $return = false;
407     //$rec = get_record("wiki","id","$wikiid","scale","-$scaleid");
408     //
409     //if (!empty($rec)  && !empty($scaleid)) {
410     //    $return = true;
411     //}
413     return $return;
416 /**
417  * Checks if scale is being used by any instance of wiki.
418  * This function was added in 1.9
419  *
420  * This is used to find out if scale used anywhere
421  * @param $scaleid int
422  * @return boolean True if the scale is used by any wiki
423  */
424 function wiki_scale_used_anywhere($scaleid) {
425     global $DB;
427     //if ($scaleid and $DB->record_exists('wiki', array('grade' => -$scaleid))) {
428     //    return true;
429     //} else {
430     //    return false;
431     //}
433     return false;
436 /**
437  * Pluginfile hook
438  *
439  * @author Josep Arus
440  */
441 function wiki_pluginfile($course, $cm, $context, $filearea, $args, $forcedownload) {
442     global $CFG;
444     if ($context->contextlevel != CONTEXT_MODULE) {
445         return false;
446     }
448     require_login($course, true, $cm);
450     require_once($CFG->dirroot . "/mod/wiki/locallib.php");
452     if ($filearea == 'attachments') {
453         $swid = (int) array_shift($args);
455         if (!$subwiki = wiki_get_subwiki($swid)) {
456             return false;
457         }
459         require_capability('mod/wiki:viewpage', $context);
461         $relativepath = implode('/', $args);
463         $fullpath = "/$context->id/mod_wiki/attachments/$swid/$relativepath";
465         $fs = get_file_storage();
466         if (!$file = $fs->get_file_by_hash(sha1($fullpath)) or $file->is_directory()) {
467             return false;
468         }
470         $lifetime = isset($CFG->filelifetime) ? $CFG->filelifetime : 86400;
472         send_stored_file($file, $lifetime, 0);
473     }
476 function wiki_search_form($cm, $search = '') {
477     global $CFG, $OUTPUT;
479     $output = '<div class="wikisearch">';
480     $output .= '<form method="post" action="' . $CFG->wwwroot . '/mod/wiki/search.php" style="display:inline">';
481     $output .= '<fieldset class="invisiblefieldset">';
482     $output .= '<input name="searchstring" type="text" size="18" value="' . s($search, true) . '" alt="search" />';
483     $output .= '<input name="courseid" type="hidden" value="' . $cm->course . '" />';
484     $output .= '<input name="cmid" type="hidden" value="' . $cm->id . '" />';
485     $output .= '<input name="searchwikicontent" type="hidden" value="1" />';
486     $output .= ' <input value="' . get_string('searchwikis', 'wiki') . '" type="submit" />';
487     $output .= '</fieldset>';
488     $output .= '</form>';
489     $output .= '</div>';
491     return $output;
493 function wiki_extend_navigation(navigation_node $navref, $course, $module, $cm) {
494     global $CFG, $PAGE, $USER;
496     require_once($CFG->dirroot . '/mod/wiki/locallib.php');
498     $context = get_context_instance(CONTEXT_MODULE, $cm->id);
499     $url = $PAGE->url;
500     $userid = 0;
501     if ($module->wikimode == 'individual') {
502         $userid = $USER->id;
503     }
505     if (!$wiki = wiki_get_wiki($cm->instance)) {
506         return false;
507     }
509     if (!$gid = groups_get_activity_group($cm)) {
510         $gid = 0;
511     }
512     if (!$subwiki = wiki_get_subwiki_by_group($cm->instance, $gid, $userid)) {
513         return null;
514     } else {
515         $swid = $subwiki->id;
516     }
518     $pageid = $url->param('pageid');
519     $cmid = $url->param('id');
520     if (empty($pageid) && !empty($cmid)) {
521         // wiki main page
522         $page = wiki_get_page_by_title($swid, $wiki->firstpagetitle);
523         $pageid = $page->id;
524     }
526     if (has_capability('mod/wiki:createpage', $context)) {
527         $link = new moodle_url('/mod/wiki/create.php', array('action' => 'new', 'swid' => $swid));
528         $node = $navref->add(get_string('newpage', 'wiki'), $link, navigation_node::TYPE_SETTING);
529     }
531     if (is_numeric($pageid)) {
533         if (has_capability('mod/wiki:viewpage', $context)) {
534             $link = new moodle_url('/mod/wiki/view.php', array('pageid' => $pageid));
535             $node = $navref->add(get_string('view', 'wiki'), $link, navigation_node::TYPE_SETTING);
536         }
538         if (has_capability('mod/wiki:editpage', $context)) {
539             $link = new moodle_url('/mod/wiki/edit.php', array('pageid' => $pageid));
540             $node = $navref->add(get_string('edit', 'wiki'), $link, navigation_node::TYPE_SETTING);
541         }
543         if (has_capability('mod/wiki:viewcomment', $context)) {
544             $link = new moodle_url('/mod/wiki/comments.php', array('pageid' => $pageid));
545             $node = $navref->add(get_string('comments', 'wiki'), $link, navigation_node::TYPE_SETTING);
546         }
548         if (has_capability('mod/wiki:viewpage', $context)) {
549             $link = new moodle_url('/mod/wiki/history.php', array('pageid' => $pageid));
550             $node = $navref->add(get_string('history', 'wiki'), $link, navigation_node::TYPE_SETTING);
551         }
553         if (has_capability('mod/wiki:viewpage', $context)) {
554             $link = new moodle_url('/mod/wiki/map.php', array('pageid' => $pageid));
555             $node = $navref->add(get_string('map', 'wiki'), $link, navigation_node::TYPE_SETTING);
556         }
558         if (has_capability('mod/wiki:viewpage', $context)) {
559             $link = new moodle_url('/mod/wiki/files.php', array('pageid' => $pageid));
560             $node = $navref->add(get_string('files', 'wiki'), $link, navigation_node::TYPE_SETTING);
561         }
562     }
564 /**
565  * Returns all other caps used in wiki module
566  *
567  * @return array
568  */
569 function wiki_get_extra_capabilities() {
570     return array('moodle/comment:view', 'moodle/comment:post', 'moodle/comment:delete');
573 /**
574  * Running addtional permission check on plugin, for example, plugins
575  * may have switch to turn on/off comments option, this callback will
576  * affect UI display, not like pluginname_comment_validate only throw
577  * exceptions.
578  * Capability check has been done in comment->check_permissions(), we
579  * don't need to do it again here.
580  *
581  * @param stdClass $comment_param {
582  *              context  => context the context object
583  *              courseid => int course id
584  *              cm       => stdClass course module object
585  *              commentarea => string comment area
586  *              itemid      => int itemid
587  * }
588  * @return array
589  */
590 function wiki_comment_permissions($comment_param) {
591     return array('post'=>true, 'view'=>true);
594 /**
595  * Validate comment parameter before perform other comments actions
596  *
597  * @param stdClass $comment_param {
598  *              context  => context the context object
599  *              courseid => int course id
600  *              cm       => stdClass course module object
601  *              commentarea => string comment area
602  *              itemid      => int itemid
603  * }
604  * @return boolean
605  */
606 function wiki_comment_validate($comment_param) {
607     global $DB, $CFG;
608     require_once($CFG->dirroot . '/mod/wiki/locallib.php');
609     // validate comment area
610     if ($comment_param->commentarea != 'wiki_page') {
611         throw new comment_exception('invalidcommentarea');
612     }
613     // validate itemid
614     if (!$record = $DB->get_record('wiki_pages', array('id'=>$comment_param->itemid))) {
615         throw new comment_exception('invalidcommentitemid');
616     }
617     if (!$subwiki = wiki_get_subwiki($record->subwikiid)) {
618         throw new comment_exception('invalidsubwikiid');
619     }
620     if (!$wiki = wiki_get_wiki_from_pageid($comment_param->itemid)) {
621         throw new comment_exception('invalidid', 'data');
622     }
623     if (!$course = $DB->get_record('course', array('id'=>$wiki->course))) {
624         throw new comment_exception('coursemisconf');
625     }
626     if (!$cm = get_coursemodule_from_instance('wiki', $wiki->id, $course->id)) {
627         throw new comment_exception('invalidcoursemodule');
628     }
629     $context = get_context_instance(CONTEXT_MODULE, $cm->id);
630     // group access
631     if ($subwiki->groupid) {
632         $groupmode = groups_get_activity_groupmode($cm, $course);
633         if ($groupmode == SEPARATEGROUPS and !has_capability('moodle/site:accessallgroups', $context)) {
634             if (!groups_is_member($subwiki->groupid)) {
635                 throw new comment_exception('notmemberofgroup');
636             }
637         }
638     }
639     // validate context id
640     if ($context->id != $comment_param->context->id) {
641         throw new comment_exception('invalidcontext');
642     }
643     // validation for comment deletion
644     if (!empty($comment_param->commentid)) {
645         if ($comment = $DB->get_record('comments', array('id'=>$comment_param->commentid))) {
646             if ($comment->commentarea != 'wiki_page') {
647                 throw new comment_exception('invalidcommentarea');
648             }
649             if ($comment->contextid != $context->id) {
650                 throw new comment_exception('invalidcontext');
651             }
652             if ($comment->itemid != $comment_param->itemid) {
653                 throw new comment_exception('invalidcommentitemid');
654             }
655         } else {
656             throw new comment_exception('invalidcommentid');
657         }
658     }
659     return true;
662 /**
663  * Return a list of page types
664  * @param string $pagetype current page type
665  * @param stdClass $parentcontext Block's parent context
666  * @param stdClass $currentcontext Current context of block
667  */
668 function wiki_page_type_list($pagetype, $parentcontext, $currentcontext) {
669     $module_pagetype = array(
670         'mod-wiki-*'=>get_string('page-mod-wiki-x', 'wiki'),
671         'mod-wiki-view'=>get_string('page-mod-wiki-view', 'wiki'),
672         'mod-wiki-comments'=>get_string('page-mod-wiki-comments', 'wiki'),
673         'mod-wiki-history'=>get_string('page-mod-wiki-history', 'wiki'),
674         'mod-wiki-map'=>get_string('page-mod-wiki-map', 'wiki')
675     );
676     return $module_pagetype;