mod/glossary/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/>.
  16 /**
  17  * Glossary module external API
  18  *
  19  * @package    mod_glossary
  20  * @category   external
  21  * @copyright  2015 Costantino Cito <ccito@cvaconsulting.com>
  22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23  * @since      Moodle 3.0
  24  */
  25 defined('MOODLE_INTERNAL') || die;
  26 require_once("$CFG->libdir/externallib.php");
  27 /**
  28  * Glossary module external functions
  29  *
  30  * @package    mod_glossary
  31  * @category   external
  32  * @copyright  2015 Costantino Cito <ccito@cvaconsulting.com>
  33  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  34  * @since      Moodle 3.0
  35  */
  36 class mod_glossary_external extends external_api {
  37     /**
  38      * Describes the parameters for get_glossaries_by_courses.
  39      *
  40      * @return external_external_function_parameters
  41      * @since Moodle 3.0
  42      */
  43     public static function get_glossaries_by_courses_parameters() {
  44         return new external_function_parameters (
  45             array(
  46                 'courseids' => new external_multiple_structure(
  47                     new external_value(PARAM_INT, 'course id'),
  48                     'Array of course ids', VALUE_DEFAULT, array()
  49                 ),
  50             )
  51         );
  52     }
  53     /**
  54      * Returns a list of glossaries in a provided list of courses,
  55      * if no list is provided all glossaries that the user can view will be returned.
  56      *
  57      * @param array $courseids the course ids
  58      * @return array of glossaries details
  59      * @since Moodle 3.0
  60      */
  61     public static function get_glossaries_by_courses($courseids = array()) {
  62         global $CFG;
  63         $params = self::validate_parameters(self::get_glossaries_by_courses_parameters(), array('courseids' => $courseids));
  64         $warnings = array();
  65         if (!empty($params['courseids'])) {
  66             $courses = array();
  67             $courseids = $params['courseids'];
  68         } else {
  69             $courses = enrol_get_my_courses();
  70             $courseids = array_keys($courses);
  71         }
  72         // Array to store the glossaries to return.
  73         $arrglossaries = array();
  74         // Ensure there are courseids to loop through.
  75         if (!empty($courseids)) {
  76             // Array of the courses we are going to retrieve the glossaries from.
  77             $arraycourses = array();
  78             // Go through the courseids.
  79             foreach ($courseids as $cid) {
  80                 // Check the user can function in this context.
  81                 try {
  82                     $context = context_course::instance($cid);
  83                     self::validate_context($context);
  84                     if (has_capability('mod/glossary:view', $context)) {
  85                         // Check if this course was already loaded (by enrol_get_my_courses).
  86                         if (!isset($courses[$cid])) {
  87                             $courses[$cid] = get_course($cid);
  88                         }
  89                         $arraycourses[$cid] = $courses[$cid];
  90                     } else {
  91                         $warnings[] = array(
  92                             'item' => 'course',
  93                             'itemid' => $cid,
  94                             'warningcode' => '2',
  95                             'message' => get_string('missingrequiredcapability', 'webservice', 'mod/glossary:view')
  96                         );
  97                     }
  98                 } catch (Exception $e) {
  99                     $warnings[] = array(
 100                         'item' => 'course',
 101                         'itemid' => $cid,
 102                         'warningcode' => '1',
 103                         'message' => 'No access rights in course context '.$e->getMessage()
 104                     );
 105                 }
 106             }
 107             // Get the glossaries in this course, this function checks users visibility permissions.
 108             // We can avoid then additional validate_context calls.
 109             $glossaries = get_all_instances_in_courses("glossary", $arraycourses);
 110             foreach ($glossaries as $glossary) {
 111                 $glossarycontext = context_module::instance($glossary->coursemodule);
 112                 // Entry to return.
 113                 $glossarydetails = array();
 114                 // First, we return information that any user can see in the web interface.
 115                 $glossarydetails['id'] = $glossary->id;
 116                 $glossarydetails['coursemodule']      = $glossary->coursemodule;
 117                 $glossarydetails['course']            = $glossary->course;
 118                 $glossarydetails['name']              = $glossary->name;
 119                 // Format intro.
 120                 list($glossarydetails['intro'], $glossarydetails['introformat']) =
 121                     external_format_text($glossary->intro, $glossary->introformat,
 122                                             $glossarycontext->id, 'mod_glossary', 'intro', null);
 123                 $glossarydetails['allowduplicatedentries'] = $glossary->allowduplicatedentries;
 124                 $glossarydetails['displayformat']          = $glossary->displayformat;
 125                 $glossarydetails['mainglossary']           = $glossary->mainglossary;
 126                 $glossarydetails['showspecial']            = $glossary->showspecial;
 127                 $glossarydetails['showalphabet']           = $glossary->showalphabet;
 128                 $glossarydetails['showall']                = $glossary->showall;
 129                 $glossarydetails['allowcomments']          = $glossary->allowcomments;
 130                 $glossarydetails['allowprintview']         = $glossary->allowprintview;
 131                 $glossarydetails['usedynalink']            = $glossary->usedynalink;
 132                 $glossarydetails['defaultapproval']        = $glossary->defaultapproval;
 133                 $glossarydetails['approvaldisplayformat']  = $glossary->approvaldisplayformat;
 134                 $glossarydetails['globalglossary']         = $glossary->globalglossary;
 135                 $glossarydetails['entbypage']              = $glossary->entbypage;
 136                 $glossarydetails['editalways']             = $glossary->editalways;
 137                 $glossarydetails['rsstype']                = $glossary->rsstype;
 138                 $glossarydetails['rssarticles']            = $glossary->rssarticles;
 139                 $glossarydetails['assessed']               = $glossary->assessed;
 140                 $glossarydetails['assesstimestart']        = $glossary->assesstimestart;
 141                 $glossarydetails['assesstimefinish']       = $glossary->assesstimefinish;
 142                 $glossarydetails['scale']                  = $glossary->scale;
 143                 if (has_capability('moodle/course:manageactivities', $glossarycontext)) {
 144                     $glossarydetails['timecreated']            = $glossary->timecreated;
 145                     $glossarydetails['timemodified']           = $glossary->timemodified;
 146                     $glossarydetails['completionentries']      = $glossary->completionentries;
 147                     $glossarydetails['section']                = $glossary->section;
 148                     $glossarydetails['visible']                = $glossary->visible;
 149                     $glossarydetails['groupmode']              = $glossary->groupmode;
 150                     $glossarydetails['groupingid']             = $glossary->groupingid;
 151                 }
 152                 $arrglossaries[] = $glossarydetails;
 153             }
 154         }
 155         $result = array();
 156         $result['glossaries'] = $arrglossaries;
 157         $result['warnings'] = $warnings;
 158         return $result;
 159     }
 160     /**
 161      * Describes the get_glossaries_by_courses return value.
 162      *
 163      * @return external_single_structure
 164      * @since Moodle 3.0
 165      */
 166     public static function get_glossaries_by_courses_returns() {
 167         return new external_single_structure(
 168             array(
 169                 'glossaries' => new external_multiple_structure(
 170                     new external_single_structure(
 171                         array(
 172                             'id' => new external_value(PARAM_INT, 'Glossary id'),
 173                             'coursemodule' => new external_value(PARAM_INT, 'Course module id'),
 174                             'course' => new external_value(PARAM_TEXT, 'Course id'),
 175                             'name' => new external_value(PARAM_TEXT, 'Glossary name'),
 176                             'intro' => new external_value(PARAM_RAW, 'The Glossary intro'),
 177                             'introformat' => new external_format_value('intro'),
 178                             'allowduplicatedentries' => new external_value(PARAM_INT, 'If enabled, multiple entries can have the'.
 179                                                                                                             ' same concept name'),
 180                             'displayformat' => new external_value(PARAM_TEXT, 'display format type'),
 181                             'mainglossary'  => new external_value(PARAM_INT, 'main glossary'),
 182                             'showspecial'   => new external_value(PARAM_INT, 'If enabled, participants can browse the glossary by'.
 183                                                                                            ' special characters, such as @ and #'),
 184                             'showalphabet'  => new external_value(PARAM_INT, 'If enabled, participants can browse the glossary by'.
 185                                                                                                        ' letters of the alphabet'),
 186                             'showall'       => new external_value(PARAM_INT, 'If enabled, participants can browse all entries '.
 187                                                                                                                      ' at once'),
 188                             'allowcomments' => new external_value(PARAM_INT, 'If enabled, all participants with permission to '.
 189                                                              'create comments will be able to add comments to glossary entries'),
 190                             'allowprintview' => new external_value(PARAM_INT, 'If enabled, students are provided with a link to a '.
 191                                              ' printer-friendly version of the glossary. The link is always available to teachers'),
 192                             'usedynalink' => new external_value(PARAM_INT, 'If site-wide glossary auto-linking has been enabled by'.
 193                                             ' an administrator and this checkbox is ticked, the entry will be automatically linked'.
 194                                                ' wherever the concept words and phrases appear throughout the rest of the course.'),
 195                             'defaultapproval' => new external_value(PARAM_INT, 'If set to no, entries require approving by a '.
 196                                                                               'teacher before they are viewable by everyone.'),
 197                             'approvaldisplayformat' => new external_value(PARAM_TEXT, 'When approving glossary items you may wish'.
 198                                                                                              ' to use a different display format'),
 199                             'globalglossary' => new external_value(PARAM_INT, ''),
 200                             'entbypage' => new external_value(PARAM_INT, 'Entries shown per page'),
 201                             'editalways' => new external_value(PARAM_INT, 'Always allow editing'),
 202                             'rsstype' => new external_value(PARAM_INT, 'To enable the RSS feed for this activity, select either'.
 203                                                    ' concepts with author or concepts without author to be included in the feed'),
 204                             'rssarticles' => new external_value(PARAM_INT, 'This setting specifies the number of glossary entry'.
 205                                                   ' concepts to include in the RSS feed. Between 5 and 20 generally acceptable'),
 206                             'assessed' => new external_value(PARAM_INT, 'assessed'),
 207                             'assesstimestart' => new external_value(PARAM_RAW, 'assess time start'),
 208                             'assesstimefinish' => new external_value(PARAM_RAW, 'assess time finish'),
 209                             'scale' => new external_value(PARAM_INT, 'scale'),
 210                             'timecreated' => new external_value(PARAM_RAW, 'time created', VALUE_OPTIONAL),
 211                             'timemodified' => new external_value(PARAM_RAW, 'time modified', VALUE_OPTIONAL),
 212                             'completionentries' => new external_value(PARAM_INT, 'completion entries', VALUE_OPTIONAL),
 213                             'section' => new external_value(PARAM_INT, 'section', VALUE_OPTIONAL),
 214                             'visible' => new external_value(PARAM_INT, 'visible', VALUE_OPTIONAL),
 215                             'groupmode' => new external_value(PARAM_INT, 'group mode', VALUE_OPTIONAL),
 216                             'groupingid' => new external_value(PARAM_INT, 'grouping id', VALUE_OPTIONAL),
 217                         ), 'Glossaries'
 218                     )
 219                 ),
 220                 'warnings' => new external_warnings(),
 221             )
 222         );
 223     }
 224 }