[Summary view]

Differences Between: [Versions 310 and 401]

   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  abstract class feedback_item_base {
  18  
  19      /** @var string type of the element, should be overridden by each item type */
  20      protected $type;
  21  
  22      /** @var feedback_item_form */
  23      protected $item_form;
  24  
  25      /** @var stdClass */
  26      protected $item;
  27  
  28      /**
  29       * constructor
  30       */
  31      public function __construct() {
  32      }
  33  
  34      /**
  35       * Displays the form for editing an item
  36       *
  37       * this function only can used after the call of build_editform()
  38       */
  39      public function show_editform() {
  40          $this->item_form->display();
  41      }
  42  
  43      /**
  44       * Checks if the editing form was cancelled
  45       *
  46       * @return bool
  47       */
  48      public function is_cancelled() {
  49          return $this->item_form->is_cancelled();
  50      }
  51  
  52      /**
  53       * Gets submitted data from the edit form and saves it in $this->item
  54       *
  55       * @return bool
  56       */
  57      public function get_data() {
  58          if ($this->item !== null) {
  59              return true;
  60          }
  61          if ($this->item = $this->item_form->get_data()) {
  62              return true;
  63          }
  64          return false;
  65      }
  66  
  67      /**
  68       * Set the item data (to be used by data generators).
  69       *
  70       * @param stdClass $itemdata the item data to set
  71       * @since Moodle 3.3
  72       */
  73      public function set_data($itemdata) {
  74          $this->item = $itemdata;
  75      }
  76  
  77      /**
  78       * Creates and returns an instance of the form for editing the item
  79       *
  80       * @param stdClass $item
  81       * @param stdClass $feedback
  82       * @param cm_info|stdClass $cm
  83       */
  84      abstract public function build_editform($item, $feedback, $cm);
  85  
  86      /**
  87       * Saves the item after it has been edited (or created)
  88       */
  89      abstract public function save_item();
  90  
  91      /**
  92       * Converts the value from complete_form data to the string value that is stored in the db.
  93       * @param mixed $value element from mod_feedback_complete_form::get_data() with the name $item->typ.'_'.$item->id
  94       * @return string
  95       */
  96      public function create_value($value) {
  97          return strval($value);
  98      }
  99  
 100      /**
 101       * Compares the dbvalue with the dependvalue
 102       *
 103       * @param stdClass $item
 104       * @param string $dbvalue is the value input by user in the format as it is stored in the db
 105       * @param string $dependvalue is the value that it needs to be compared against
 106       */
 107      public function compare_value($item, $dbvalue, $dependvalue) {
 108          return strval($dbvalue) === strval($dependvalue);
 109      }
 110  
 111      /**
 112       * Wether this item type has a value that is expected from the user and saved in the stored values.
 113       * @return int
 114       */
 115      public function get_hasvalue() {
 116          return 1;
 117      }
 118  
 119      /**
 120       * Wether this item can be set as both required and not
 121       * @return bool
 122       */
 123      public function can_switch_require() {
 124          return true;
 125      }
 126  
 127      /**
 128       * Adds summary information about an item to the Excel export file
 129       *
 130       * @param object $worksheet a reference to the pear_spreadsheet-object
 131       * @param integer $row_offset
 132       * @param stdClass $xls_formats see analysis_to_excel.php
 133       * @param object $item the db-object from feedback_item
 134       * @param integer $groupid
 135       * @param integer $courseid
 136       * @return integer the new row_offset
 137       */
 138      abstract public function excelprint_item(&$worksheet, $row_offset,
 139                                        $xls_formats, $item,
 140                                        $groupid, $courseid = false);
 141  
 142      /**
 143       * Prints analysis for the current item
 144       *
 145       * @param $item the db-object from feedback_item
 146       * @param string $itemnr
 147       * @param integer $groupid
 148       * @param integer $courseid
 149       * @return integer the new itemnr
 150       */
 151      abstract public function print_analysed($item, $itemnr = '', $groupid = false, $courseid = false);
 152  
 153      /**
 154       * Prepares the value for exporting to Excel
 155       *
 156       * @param object $item the db-object from feedback_item
 157       * @param object $value object with item-related value from feedback_values in the 'value' property
 158       * @return string
 159       */
 160      abstract public function get_printval($item, $value);
 161  
 162      /**
 163       * Returns the formatted name of the item for the complete form or response view
 164       *
 165       * @param stdClass $item
 166       * @param bool $withpostfix
 167       * @return string
 168       */
 169      public function get_display_name($item, $withpostfix = true) {
 170          return format_text($item->name, FORMAT_HTML, array('noclean' => true, 'para' => false)) .
 171                  ($withpostfix ? $this->get_display_name_postfix($item) : '');
 172      }
 173  
 174      /**
 175       * Returns the postfix to be appended to the display name that is based on other settings
 176       *
 177       * @param stdClass $item
 178       * @return string
 179       */
 180      public function get_display_name_postfix($item) {
 181          return '';
 182      }
 183  
 184      /**
 185       * Adds an input element to the complete form
 186       *
 187       * This method is called:
 188       * - to display the form when user completes feedback
 189       * - to display existing elements when teacher edits the feedback items
 190       * - to display the feedback preview (print.php)
 191       * - to display the completed response
 192       * - to preview a feedback template
 193       *
 194       * If it is important which mode the form is in, use $form->get_mode()
 195       *
 196       * Each item type must add a single form element with the name $item->typ.'_'.$item->id
 197       * This element must always be present in form data even if nothing is selected (i.e. use advcheckbox and not checkbox).
 198       * To add an element use either:
 199       * $form->add_form_element() - adds a single element to the form
 200       * $form->add_form_group_element() - adds a group element to the form
 201       *
 202       * Other useful methods:
 203       * $form->get_item_value()
 204       * $form->set_element_default()
 205       * $form->add_validation_rule()
 206       * $form->set_element_type()
 207       *
 208       * The element must support freezing so it can be used for viewing the response as well.
 209       * If the desired form element does not support freezing, check $form->is_frozen()
 210       * and create a static element instead.
 211       *
 212       * @param stdClass $item
 213       * @param mod_feedback_complete_form $form
 214       */
 215      abstract public function complete_form_element($item, $form);
 216  
 217      /**
 218       * Returns the list of actions allowed on this item in the edit mode
 219       *
 220       * @param stdClass $item
 221       * @param stdClass $feedback
 222       * @param cm_info $cm
 223       * @return action_menu_link[]
 224       */
 225      public function edit_actions($item, $feedback, $cm) {
 226          $actions = array();
 227  
 228          $strupdate = get_string('edit_item', 'feedback');
 229          $actions['update'] = new action_menu_link_secondary(
 230              new moodle_url('/mod/feedback/edit_item.php', array('id' => $item->id)),
 231              new pix_icon('t/edit', $strupdate, 'moodle', array('class' => 'iconsmall', 'title' => '')),
 232              $strupdate,
 233              array('class' => 'editing_update', 'data-action' => 'update')
 234          );
 235  
 236          if ($this->can_switch_require()) {
 237              if ($item->required == 1) {
 238                  $buttontitle = get_string('switch_item_to_not_required', 'feedback');
 239                  $buttonimg = 'required';
 240              } else {
 241                  $buttontitle = get_string('switch_item_to_required', 'feedback');
 242                  $buttonimg = 'notrequired';
 243              }
 244              $actions['required'] = new action_menu_link_secondary(
 245                  new moodle_url('/mod/feedback/edit.php', array('id' => $cm->id,
 246                      'switchitemrequired' => $item->id, 'sesskey' => sesskey())),
 247                  new pix_icon($buttonimg, $buttontitle, 'feedback', array('class' => 'iconsmall', 'title' => '')),
 248                  $buttontitle,
 249                  array('class' => 'editing_togglerequired', 'data-action' => 'togglerequired')
 250              );
 251          }
 252  
 253          $strdelete = get_string('delete_item', 'feedback');
 254          $actions['delete'] = new action_menu_link_secondary(
 255              new moodle_url('/mod/feedback/edit.php', array('id' => $cm->id, 'deleteitem' => $item->id, 'sesskey' => sesskey())),
 256              new pix_icon('t/delete', $strdelete, 'moodle', array('class' => 'iconsmall', 'title' => '')),
 257              $strdelete,
 258              array('class' => 'editing_delete', 'data-action' => 'delete')
 259          );
 260  
 261          return $actions;
 262      }
 263  
 264      /**
 265       * Return extra data for external functions.
 266       *
 267       * Some items may have additional configuration data or default values that should be returned for external functions:
 268       * - Info elements: The default value information (course or category name)
 269       * - Captcha: The recaptcha challenge hash key
 270       *
 271       * @param stdClass $item the item object
 272       * @return str the data, may be json_encoded for large structures
 273       */
 274      public function get_data_for_external($item) {
 275          return null;
 276      }
 277  
 278      /**
 279       * Return the analysis data ready for external functions.
 280       *
 281       * @param stdClass $item     the item (question) information
 282       * @param int      $groupid  the group id to filter data (optional)
 283       * @param int      $courseid the course id (optional)
 284       * @return array an array of data with non scalar types json encoded
 285       * @since  Moodle 3.3
 286       */
 287      abstract public function get_analysed_for_external($item, $groupid = false, $courseid = false);
 288  }
 289  
 290  //a dummy class to realize pagebreaks
 291  class feedback_item_pagebreak extends feedback_item_base {
 292      protected $type = "pagebreak";
 293  
 294      public function show_editform() {
 295      }
 296  
 297      /**
 298       * Checks if the editing form was cancelled
 299       * @return bool
 300       */
 301      public function is_cancelled() {
 302      }
 303      public function get_data() {
 304      }
 305      public function build_editform($item, $feedback, $cm) {
 306      }
 307      public function save_item() {
 308      }
 309      public function create_value($data) {
 310      }
 311      public function get_hasvalue() {
 312          return 0;
 313      }
 314      public function excelprint_item(&$worksheet, $row_offset,
 315                              $xls_formats, $item,
 316                              $groupid, $courseid = false) {
 317      }
 318  
 319      public function print_analysed($item, $itemnr = '', $groupid = false, $courseid = false) {
 320      }
 321      public function get_printval($item, $value) {
 322      }
 323      public function can_switch_require() {
 324          return false;
 325      }
 326  
 327      /**
 328       * Adds an input element to the complete form
 329       *
 330       * @param stdClass $item
 331       * @param mod_feedback_complete_form $form
 332       */
 333      public function complete_form_element($item, $form) {
 334          $form->add_form_element($item,
 335              ['static',
 336                  $item->typ.'_'.$item->id,
 337                  '',
 338                  html_writer::empty_tag('hr', ['class' => 'feedback_pagebreak', 'id' => 'feedback_item_' . $item->id])
 339              ]);
 340      }
 341  
 342      /**
 343       * Returns the list of actions allowed on this item in the edit mode
 344       *
 345       * @param stdClass $item
 346       * @param stdClass $feedback
 347       * @param cm_info $cm
 348       * @return action_menu_link[]
 349       */
 350      public function edit_actions($item, $feedback, $cm) {
 351          $actions = array();
 352          $strdelete = get_string('delete_pagebreak', 'feedback');
 353          $actions['delete'] = new action_menu_link_secondary(
 354              new moodle_url('/mod/feedback/edit.php', array('id' => $cm->id, 'deleteitem' => $item->id, 'sesskey' => sesskey())),
 355              new pix_icon('t/delete', $strdelete, 'moodle', array('class' => 'iconsmall', 'title' => '')),
 356              $strdelete,
 357              array('class' => 'editing_delete', 'data-action' => 'delete')
 358          );
 359          return $actions;
 360      }
 361  
 362      /**
 363       * Return the analysis data ready for external functions.
 364       *
 365       * @param stdClass $item     the item (question) information
 366       * @param int      $groupid  the group id to filter data (optional)
 367       * @param int      $courseid the course id (optional)
 368       * @return array an array of data with non scalar types json encoded
 369       * @since  Moodle 3.3
 370       */
 371      public function get_analysed_for_external($item, $groupid = false, $courseid = false) {
 372          return;
 373      }
 374  }