[Summary view] [Print] [Text view]

   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   * Database module external API
  19   *
  20   * @package    mod_data
  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 2.9
  25   */
  26  
  27  defined('MOODLE_INTERNAL') || die;
  28  
  29  require_once("$CFG->libdir/externallib.php");
  30  
  31  /**
  32   * Database module external functions
  33   *
  34   * @package    mod_data
  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 2.9
  39   */
  40  class mod_data_external extends external_api {
  41  
  42      /**
  43       * Describes the parameters for get_databases_by_courses.
  44       *
  45       * @return external_external_function_parameters
  46       * @since Moodle 2.9
  47       */
  48      public static function get_databases_by_courses_parameters() {
  49          return new external_function_parameters (
  50              array(
  51                  'courseids' => new external_multiple_structure(
  52                      new external_value(PARAM_INT, 'course id', VALUE_REQUIRED),
  53                      'Array of course ids', VALUE_DEFAULT, array()
  54                  ),
  55              )
  56          );
  57      }
  58  
  59      /**
  60       * Returns a list of databases in a provided list of courses,
  61       * if no list is provided all databases that the user can view will be returned.
  62       *
  63       * @param array $courseids the course ids
  64       * @return array the database details
  65       * @since Moodle 2.9
  66       */
  67      public static function get_databases_by_courses($courseids = array()) {
  68          global $CFG;
  69  
  70          $params = self::validate_parameters(self::get_databases_by_courses_parameters(), array('courseids' => $courseids));
  71          $warnings = array();
  72  
  73          $mycourses = array();
  74          if (empty($params['courseids'])) {
  75              $mycourses = enrol_get_my_courses();
  76              $params['courseids'] = array_keys($mycourses);
  77          }
  78  
  79          // Array to store the databases to return.
  80          $arrdatabases = array();
  81  
  82          // Ensure there are courseids to loop through.
  83          if (!empty($params['courseids'])) {
  84  
  85              list($dbcourses, $warnings) = external_util::validate_courses($params['courseids'], $mycourses);
  86  
  87              // Get the databases in this course, this function checks users visibility permissions.
  88              // We can avoid then additional validate_context calls.
  89              $databases = get_all_instances_in_courses("data", $dbcourses);
  90  
  91              foreach ($databases as $database) {
  92  
  93                  $datacontext = context_module::instance($database->coursemodule);
  94  
  95                  // Entry to return.
  96                  $newdb = array();
  97  
  98                  // First, we return information that any user can see in the web interface.
  99                  $newdb['id'] = $database->id;
 100                  $newdb['coursemodule'] = $database->coursemodule;
 101                  $newdb['course'] = $database->course;
 102                  $newdb['name']  = external_format_string($database->name, $datacontext->id);
 103                  // Format intro.
 104                  list($newdb['intro'], $newdb['introformat']) =
 105                      external_format_text($database->intro, $database->introformat,
 106                                              $datacontext->id, 'mod_data', 'intro', null);
 107                  $newdb['introfiles'] = external_util::get_area_files($datacontext->id, 'mod_data', 'intro', false, false);
 108  
 109                  // This information should be only available if the user can see the database entries.
 110                  if (has_capability('mod/data:viewentry', $datacontext)) {
 111                      $viewablefields = array('comments', 'timeavailablefrom', 'timeavailableto', 'timeviewfrom',
 112                                              'timeviewto', 'requiredentries', 'requiredentriestoview');
 113  
 114                      // This is for avoid a long repetitive list and for
 115                      // checking that we are retrieving all the required fields.
 116                      foreach ($viewablefields as $field) {
 117                          // We do not use isset because it won't work for existing null values.
 118                          if (!property_exists($database, $field)) {
 119                              throw new invalid_response_exception('Missing database module required field: ' . $field);
 120                          }
 121                          $newdb[$field] = $database->{$field};
 122                      }
 123                  }
 124  
 125                  // Check additional permissions for returning optional private settings.
 126                  // I avoid intentionally to use can_[add|update]_moduleinfo.
 127                  if (has_capability('moodle/course:manageactivities', $datacontext)) {
 128  
 129                      $additionalfields = array('maxentries', 'rssarticles', 'singletemplate', 'listtemplate',
 130                          'listtemplateheader', 'listtemplatefooter', 'addtemplate', 'rsstemplate', 'rsstitletemplate',
 131                          'csstemplate', 'jstemplate', 'asearchtemplate', 'approval', 'manageapproved', 'scale', 'assessed', 'assesstimestart',
 132                          'assesstimefinish', 'defaultsort', 'defaultsortdir', 'editany', 'notification', 'timemodified');
 133  
 134                      // This is for avoid a long repetitive list.
 135                      foreach ($additionalfields as $field) {
 136                          if (property_exists($database, $field)) {
 137                              $newdb[$field] = $database->{$field};
 138                          }
 139                      }
 140                  }
 141  
 142                  $arrdatabases[] = $newdb;
 143              }
 144          }
 145  
 146          $result = array();
 147          $result['databases'] = $arrdatabases;
 148          $result['warnings'] = $warnings;
 149          return $result;
 150      }
 151  
 152      /**
 153       * Describes the get_databases_by_courses return value.
 154       *
 155       * @return external_single_structure
 156       * @since Moodle 2.9
 157       */
 158      public static function get_databases_by_courses_returns() {
 159  
 160          return new external_single_structure(
 161              array(
 162                  'databases' => new external_multiple_structure(
 163                      new external_single_structure(
 164                          array(
 165                              'id' => new external_value(PARAM_INT, 'Database id'),
 166                              'coursemodule' => new external_value(PARAM_INT, 'Course module id'),
 167                              'course' => new external_value(PARAM_INT, 'Course id'),
 168                              'name' => new external_value(PARAM_RAW, 'Database name'),
 169                              'intro' => new external_value(PARAM_RAW, 'The Database intro'),
 170                              'introformat' => new external_format_value('intro'),
 171                              'introfiles' => new external_files('Files in the introduction text', VALUE_OPTIONAL),
 172                              'comments' => new external_value(PARAM_BOOL, 'comments enabled', VALUE_OPTIONAL),
 173                              'timeavailablefrom' => new external_value(PARAM_INT, 'timeavailablefrom field', VALUE_OPTIONAL),
 174                              'timeavailableto' => new external_value(PARAM_INT, 'timeavailableto field', VALUE_OPTIONAL),
 175                              'timeviewfrom' => new external_value(PARAM_INT, 'timeviewfrom field', VALUE_OPTIONAL),
 176                              'timeviewto' => new external_value(PARAM_INT, 'timeviewto field', VALUE_OPTIONAL),
 177                              'requiredentries' => new external_value(PARAM_INT, 'requiredentries field', VALUE_OPTIONAL),
 178                              'requiredentriestoview' => new external_value(PARAM_INT, 'requiredentriestoview field', VALUE_OPTIONAL),
 179                              'maxentries' => new external_value(PARAM_INT, 'maxentries field', VALUE_OPTIONAL),
 180                              'rssarticles' => new external_value(PARAM_INT, 'rssarticles field', VALUE_OPTIONAL),
 181                              'singletemplate' => new external_value(PARAM_RAW, 'singletemplate field', VALUE_OPTIONAL),
 182                              'listtemplate' => new external_value(PARAM_RAW, 'listtemplate field', VALUE_OPTIONAL),
 183                              'listtemplateheader' => new external_value(PARAM_RAW, 'listtemplateheader field', VALUE_OPTIONAL),
 184                              'listtemplatefooter' => new external_value(PARAM_RAW, 'listtemplatefooter field', VALUE_OPTIONAL),
 185                              'addtemplate' => new external_value(PARAM_RAW, 'addtemplate field', VALUE_OPTIONAL),
 186                              'rsstemplate' => new external_value(PARAM_RAW, 'rsstemplate field', VALUE_OPTIONAL),
 187                              'rsstitletemplate' => new external_value(PARAM_RAW, 'rsstitletemplate field', VALUE_OPTIONAL),
 188                              'csstemplate' => new external_value(PARAM_RAW, 'csstemplate field', VALUE_OPTIONAL),
 189                              'jstemplate' => new external_value(PARAM_RAW, 'jstemplate field', VALUE_OPTIONAL),
 190                              'asearchtemplate' => new external_value(PARAM_RAW, 'asearchtemplate field', VALUE_OPTIONAL),
 191                              'approval' => new external_value(PARAM_BOOL, 'approval field', VALUE_OPTIONAL),
 192                              'manageapproved' => new external_value(PARAM_BOOL, 'manageapproved field', VALUE_OPTIONAL),
 193                              'scale' => new external_value(PARAM_INT, 'scale field', VALUE_OPTIONAL),
 194                              'assessed' => new external_value(PARAM_INT, 'assessed field', VALUE_OPTIONAL),
 195                              'assesstimestart' => new external_value(PARAM_INT, 'assesstimestart field', VALUE_OPTIONAL),
 196                              'assesstimefinish' => new external_value(PARAM_INT, 'assesstimefinish field', VALUE_OPTIONAL),
 197                              'defaultsort' => new external_value(PARAM_INT, 'defaultsort field', VALUE_OPTIONAL),
 198                              'defaultsortdir' => new external_value(PARAM_INT, 'defaultsortdir field', VALUE_OPTIONAL),
 199                              'editany' => new external_value(PARAM_BOOL, 'editany field', VALUE_OPTIONAL),
 200                              'notification' => new external_value(PARAM_INT, 'notification field', VALUE_OPTIONAL),
 201                              'timemodified' => new external_value(PARAM_INT, 'Time modified', VALUE_OPTIONAL)
 202                          ), 'Database'
 203                      )
 204                  ),
 205                  'warnings' => new external_warnings(),
 206              )
 207          );
 208      }
 209  
 210  }