MDL-53638 mod_feedback: change items classes
[moodle.git] / mod / feedback / item / feedback_item_class.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/>.
17 abstract class feedback_item_base {
19     /** @var string type of the element, should be overridden by each item type */
20     protected $type;
22     /** @var feedback_item_form */
23     protected $item_form;
25     /** @var stdClass */
26     protected $item;
28     /**
29      * constructor
30      */
31     public function __construct() {
32     }
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     }
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     }
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 = $this->item_form->get_data()) {
59             return true;
60         }
61         return false;
62     }
64     /**
65      * Creates and returns an instance of the form for editing the item
66      *
67      * @param stdClass $item
68      * @param stdClass $feedback
69      * @param cm_info|stdClass $cm
70      */
71     abstract public function build_editform($item, $feedback, $cm);
73     /**
74      * Saves the item after it has been edited (or created)
75      */
76     abstract public function save_item();
78     /**
79      * Converts the value from complete_form data to the string value that is stored in the db.
80      * @param mixed $value element from mod_feedback_complete_form::get_data() with the name $item->typ.'_'.$item->id
81      * @return string
82      */
83     public function create_value($value) {
84         return strval($value);
85     }
87     /**
88      * Compares the dbvalue with the dependvalue
89      *
90      * @param stdClass $item
91      * @param string $dbvalue is the value input by user in the format as it is stored in the db
92      * @param string $dependvalue is the value that it needs to be compared against
93      */
94     public function compare_value($item, $dbvalue, $dependvalue) {
95         return strval($dbvalue) === strval($dependvalue);
96     }
98     /**
99      * Wether this item type has a value that is expected from the user and saved in the stored values.
100      * @return int
101      */
102     public function get_hasvalue() {
103         return 1;
104     }
106     /**
107      * Wether this item can be set as both required and not
108      * @return bool
109      */
110     public function can_switch_require() {
111         return true;
112     }
114     /**
115      * Adds summary information about an item to the Excel export file
116      *
117      * @param object $worksheet a reference to the pear_spreadsheet-object
118      * @param integer $row_offset
119      * @param stdClass $xls_formats see analysis_to_excel.php
120      * @param object $item the db-object from feedback_item
121      * @param integer $groupid
122      * @param integer $courseid
123      * @return integer the new row_offset
124      */
125     abstract public function excelprint_item(&$worksheet, $row_offset,
126                                       $xls_formats, $item,
127                                       $groupid, $courseid = false);
129     /**
130      * Prints analysis for the current item
131      *
132      * @param $item the db-object from feedback_item
133      * @param string $itemnr
134      * @param integer $groupid
135      * @param integer $courseid
136      * @return integer the new itemnr
137      */
138     abstract public function print_analysed($item, $itemnr = '', $groupid = false, $courseid = false);
140     /**
141      * Prepares the value for exporting to Excel
142      *
143      * @param object $item the db-object from feedback_item
144      * @param string $value a item-related value from feedback_values
145      * @return string
146      */
147     abstract public function get_printval($item, $value);
149     /**
150      * Returns the formatted name of the item for the complete form or response view
151      *
152      * @param stdClass $item
153      * @param bool $withpostfix
154      * @return string
155      */
156     public function get_display_name($item, $withpostfix = true) {
157         return format_text($item->name, FORMAT_HTML, array('noclean' => true, 'para' => false)) .
158                 ($withpostfix ? $this->get_display_name_postfix($item) : '');
159     }
161     /**
162      * Returns the postfix to be appended to the display name that is based on other settings
163      *
164      * @param stdClass $item
165      * @return string
166      */
167     public function get_display_name_postfix($item) {
168         return '';
169     }
171     /**
172      * Adds an input element to the complete form
173      *
174      * This method is called:
175      * - to display the form when user completes feedback
176      * - to display existing elements when teacher edits the feedback items
177      * - to display the feedback preview (print.php)
178      * - to display the completed response
179      * - to preview a feedback template
180      *
181      * If it is important which mode the form is in, use $form->get_mode()
182      *
183      * Each item type must add a single form element with the name $item->typ.'_'.$item->id
184      * To add an element use either:
185      * $form->add_form_element() - adds a single element to the form
186      * $form->add_form_group_element() - adds a group element to the form
187      *
188      * Other useful methods:
189      * $form->get_item_value()
190      * $form->set_element_default()
191      * $form->add_validation_rule()
192      * $form->set_element_type()
193      *
194      * The element must support freezing so it can be used for viewing the response as well.
195      * If the desired form element does not support freezing, check $form->is_frozen()
196      * and create a static element instead.
197      *
198      * @param stdClass $item
199      * @param mod_feedback_complete_form $form
200      */
201     abstract public function complete_form_element($item, $form);
203     /**
204      * Returns the list of actions allowed on this item in the edit mode
205      *
206      * @param stdClass $item
207      * @param stdClass $feedback
208      * @param cm_info $cm
209      * @return action_menu_link[]
210      */
211     public function edit_actions($item, $feedback, $cm) {
212         $actions = array();
214         $strupdate = get_string('edit_item', 'feedback');
215         $actions['update'] = new action_menu_link_secondary(
216             new moodle_url('/mod/feedback/edit_item.php', array('id' => $item->id)),
217             new pix_icon('t/edit', $strupdate, 'moodle', array('class' => 'iconsmall', 'title' => '')),
218             $strupdate,
219             array('class' => 'editing_update', 'data-action' => 'update')
220         );
222         if ($this->can_switch_require()) {
223             if ($item->required == 1) {
224                 $buttontitle = get_string('switch_item_to_not_required', 'feedback');
225                 $buttonimg = 'required';
226             } else {
227                 $buttontitle = get_string('switch_item_to_required', 'feedback');
228                 $buttonimg = 'notrequired';
229             }
230             $url = new moodle_url('/mod/feedback/edit.php', array('id' => $cm->id, 'do_show' => 'edit'));
231             $actions['required'] = new action_menu_link_secondary(
232                 new moodle_url($url, array('switchitemrequired' => $item->id)),
233                 new pix_icon($buttonimg, $buttontitle, 'feedback', array('class' => 'iconsmall', 'title' => '')),
234                 $buttontitle,
235                 array('class' => 'editing_togglerequired', 'data-action' => 'togglerequired')
236             );
237         }
239         $strdelete = get_string('delete_item', 'feedback');
240         $actions['delete'] = new action_menu_link_secondary(
241             new moodle_url('/mod/feedback/delete_item.php', array('deleteitem' => $item->id)),
242             new pix_icon('t/delete', $strdelete, 'moodle', array('class' => 'iconsmall', 'title' => '')),
243             $strdelete,
244             array('class' => 'editing_delete', 'data-action' => 'delete')
245         );
247         return $actions;
248     }
251 //a dummy class to realize pagebreaks
252 class feedback_item_pagebreak extends feedback_item_base {
253     protected $type = "pagebreak";
255     public function show_editform() {
256     }
258     /**
259      * Checks if the editing form was cancelled
260      * @return bool
261      */
262     public function is_cancelled() {
263     }
264     public function get_data() {
265     }
266     public function build_editform($item, $feedback, $cm) {
267     }
268     public function save_item() {
269     }
270     public function create_value($data) {
271     }
272     public function get_hasvalue() {
273         return 0;
274     }
275     public function excelprint_item(&$worksheet, $row_offset,
276                             $xls_formats, $item,
277                             $groupid, $courseid = false) {
278     }
280     public function print_analysed($item, $itemnr = '', $groupid = false, $courseid = false) {
281     }
282     public function get_printval($item, $value) {
283     }
284     public function can_switch_require() {
285         return false;
286     }
288     /**
289      * Adds an input element to the complete form
290      *
291      * @param stdClass $item
292      * @param mod_feedback_complete_form $form
293      */
294     public function complete_form_element($item, $form) {
295         $form->add_form_element($item,
296                 ['static', $item->typ.'_'.$item->id, '', '<hr class="feedback_pagebreak">']);
297     }
299     /**
300      * Returns the list of actions allowed on this item in the edit mode
301      *
302      * @param stdClass $item
303      * @param stdClass $feedback
304      * @param cm_info $cm
305      * @return action_menu_link[]
306      */
307     public function edit_actions($item, $feedback, $cm) {
308         $actions = array();
309         $strdelete = get_string('delete_pagebreak', 'feedback');
310         $actions['delete'] = new action_menu_link_secondary(
311             new moodle_url('/mod/feedback/delete_item.php', array('deleteitem' => $item->id)),
312             new pix_icon('t/delete', $strdelete, 'moodle', array('class' => 'iconsmall', 'title' => '')),
313             $strdelete,
314             array('class' => 'editing_delete', 'data-action' => 'delete')
315         );
316         return $actions;
317     }