Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.
   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   * The form used at the guide editor page is defined here
  19   *
  20   * @package    gradingform_guide
  21   * @copyright  2012 Dan Marsden <dan@danmarsden.com>
  22   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   */
  24  
  25  defined('MOODLE_INTERNAL') || die();
  26  
  27  require_once($CFG->dirroot.'/lib/formslib.php');
  28  require_once (__DIR__.'/guideeditor.php');
  29  MoodleQuickForm::registerElementType('guideeditor', $CFG->dirroot.'/grade/grading/form/guide/guideeditor.php',
  30      'moodlequickform_guideeditor');
  31  
  32  /**
  33   * Defines the guide edit form
  34   *
  35   * @package    gradingform_guide
  36   * @copyright  2012 Dan Marsden <dan@danmarsden.com>
  37   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  38   */
  39  class gradingform_guide_editguide extends moodleform {
  40  
  41      /**
  42       * Form element definition
  43       */
  44      public function definition() {
  45          $form = $this->_form;
  46  
  47          $form->addElement('hidden', 'areaid');
  48          $form->setType('areaid', PARAM_INT);
  49  
  50          $form->addElement('hidden', 'returnurl');
  51          $form->setType('returnurl', PARAM_LOCALURL);
  52  
  53          // Name.
  54          $form->addElement('text', 'name', get_string('name', 'gradingform_guide'),
  55              array('size' => 52, 'maxlength' => 255));
  56          $form->addRule('name', get_string('required'), 'required', null, 'client');
  57          $form->setType('name', PARAM_TEXT);
  58          $form->addRule('name', null, 'maxlength', 255, 'client');
  59  
  60          // Description.
  61          $options = gradingform_guide_controller::description_form_field_options($this->_customdata['context']);
  62          $form->addElement('editor', 'description_editor', get_string('description'), null, $options);
  63          $form->setType('description_editor', PARAM_RAW);
  64  
  65          // Guide completion status.
  66          $choices = array();
  67          $choices[gradingform_controller::DEFINITION_STATUS_DRAFT]    = html_writer::tag('span',
  68              get_string('statusdraft', 'core_grading'), array('class' => 'status draft'));
  69          $choices[gradingform_controller::DEFINITION_STATUS_READY]    = html_writer::tag('span',
  70              get_string('statusready', 'core_grading'), array('class' => 'status ready'));
  71          $form->addElement('select', 'status', get_string('guidestatus', 'gradingform_guide'), $choices)->freeze();
  72  
  73          // Guide editor.
  74          $element = $form->addElement('guideeditor', 'guide', get_string('pluginname', 'gradingform_guide'));
  75          $form->setType('guide', PARAM_RAW);
  76  
  77          $buttonarray = array();
  78          $buttonarray[] = &$form->createElement('submit', 'saveguide', get_string('saveguide', 'gradingform_guide'));
  79          if ($this->_customdata['allowdraft']) {
  80              $buttonarray[] = &$form->createElement('submit', 'saveguidedraft', get_string('saveguidedraft', 'gradingform_guide'));
  81          }
  82          $editbutton = &$form->createElement('submit', 'editguide', ' ');
  83          $editbutton->freeze();
  84          $buttonarray[] = &$editbutton;
  85          $buttonarray[] = &$form->createElement('cancel');
  86          $form->addGroup($buttonarray, 'buttonar', '', array(' '), false);
  87          $form->closeHeaderBefore('buttonar');
  88      }
  89  
  90      /**
  91       * Setup the form depending on current values. This method is called after definition(),
  92       * data submission and set_data().
  93       * All form setup that is dependent on form values should go in here.
  94       *
  95       * We remove the element status if there is no current status (i.e. guide is only being created)
  96       * so the users do not get confused
  97       */
  98      public function definition_after_data() {
  99          $form = $this->_form;
 100          $el = $form->getElement('status');
 101          if (!$el->getValue()) {
 102              $form->removeElement('status');
 103          } else {
 104              $vals = array_values($el->getValue());
 105              if ($vals[0] == gradingform_controller::DEFINITION_STATUS_READY) {
 106                  $this->findbutton('saveguide')->setValue(get_string('save', 'gradingform_guide'));
 107              }
 108          }
 109      }
 110  
 111      /**
 112       * Form vlidation.
 113       * If there are errors return array of errors ("fieldname"=>"error message"),
 114       * otherwise true if ok.
 115       *
 116       * @param array $data array of ("fieldname"=>value) of submitted data
 117       * @param array $files array of uploaded files "element_name"=>tmp_file_path
 118       * @return array of "element_name"=>"error_description" if there are errors,
 119       *               or an empty array if everything is OK (true allowed for backwards compatibility too).
 120       */
 121      public function validation($data, $files) {
 122          $err = parent::validation($data, $files);
 123          $err = array();
 124          $form = $this->_form;
 125          $guideel = $form->getElement('guide');
 126          if ($guideel->non_js_button_pressed($data['guide'])) {
 127              // If JS is disabled and button such as 'Add criterion' is pressed - prevent from submit.
 128              $err['guidedummy'] = 1;
 129          } else if (isset($data['editguide'])) {
 130              // Continue editing.
 131              $err['guidedummy'] = 1;
 132          } else if ((isset($data['saveguide']) && $data['saveguide']) ||
 133                     (isset($data['saveguidedraft']) && $data['saveguidedraft'])) {
 134              // If user attempts to make guide active - it needs to be validated.
 135              if ($guideel->validate($data['guide']) !== false) {
 136                  $err['guidedummy'] = 1;
 137              }
 138          }
 139          return $err;
 140      }
 141  
 142      /**
 143       * Return submitted data if properly submitted or returns NULL if validation fails or
 144       * if there is no submitted data.
 145       *
 146       * @return object submitted data; NULL if not valid or not submitted or cancelled
 147       */
 148      public function get_data() {
 149          $data = parent::get_data();
 150          if (!empty($data->saveguide)) {
 151              $data->status = gradingform_controller::DEFINITION_STATUS_READY;
 152          } else if (!empty($data->saveguidedraft)) {
 153              $data->status = gradingform_controller::DEFINITION_STATUS_DRAFT;
 154          }
 155          return $data;
 156      }
 157  
 158      /**
 159       * Check if there are changes in the guide and it is needed to ask user whether to
 160       * mark the current grades for re-grading. User may confirm re-grading and continue,
 161       * return to editing or cancel the changes
 162       *
 163       * @param gradingform_guide_controller $controller
 164       */
 165      public function need_confirm_regrading($controller) {
 166          $data = $this->get_data();
 167          if (isset($data->guide['regrade'])) {
 168              // We have already displayed the confirmation on the previous step.
 169              return false;
 170          }
 171          if (!isset($data->saveguide) || !$data->saveguide) {
 172              // We only need confirmation when button 'Save guide' is pressed.
 173              return false;
 174          }
 175          if (!$controller->has_active_instances()) {
 176              // Nothing to re-grade, confirmation not needed.
 177              return false;
 178          }
 179          $changelevel = $controller->update_or_check_guide($data);
 180          if ($changelevel == 0) {
 181              // No changes in the guide, no confirmation needed.
 182              return false;
 183          }
 184  
 185          // Freeze form elements and pass the values in hidden fields.
 186          // TODO description_editor does not freeze the normal way!
 187          $form = $this->_form;
 188          foreach (array('guide', 'name'/*, 'description_editor'*/) as $fieldname) {
 189              $el =& $form->getElement($fieldname);
 190              $el->freeze();
 191              $el->setPersistantFreeze(true);
 192              if ($fieldname == 'guide') {
 193                  $el->add_regrade_confirmation($changelevel);
 194              }
 195          }
 196  
 197          // Replace button text 'saveguide' and unfreeze 'Back to edit' button.
 198          $this->findbutton('saveguide')->setValue(get_string('continue'));
 199          $el =& $this->findbutton('editguide');
 200          $el->setValue(get_string('backtoediting', 'gradingform_guide'));
 201          $el->unfreeze();
 202  
 203          return true;
 204      }
 205  
 206      /**
 207       * Returns a form element (submit button) with the name $elementname
 208       *
 209       * @param string $elementname
 210       * @return HTML_QuickForm_element
 211       */
 212      protected function &findbutton($elementname) {
 213          $form = $this->_form;
 214          $buttonar =& $form->getElement('buttonar');
 215          $elements =& $buttonar->getElements();
 216          foreach ($elements as $el) {
 217              if ($el->getName() == $elementname) {
 218                  return $el;
 219              }
 220          }
 221          return null;
 222      }
 223  }