Skip to content

Commit

Permalink
adds and updates class/method docblocks as applicable.
Browse files Browse the repository at this point in the history 
most of it is moot, but PHPdoc is very pendantic about this, so i've
added the least amount of docs necessary here.
Most of it has been copied from whatever base class these methods were
inherited from.
  • Loading branch information
@stopfstedt
stopfstedt committed Mar 16, 2024
1 parent dcdca96 commit ba596fe
Show file tree
Hide file tree
Showing 6 changed files with 182 additions and 4 deletions.
4 changes: 3 additions & 1 deletion backup/moodle2/backup_qtype_knowledgecheck_plugin.class.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,14 +15,16 @@
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* Backup plugin for the Knowledge check question type.
*
* @package qtype_knowledgecheck
* @subpackage backup-moodle2
* @copyright (c) The Regents of the University of California
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

/**
* Provides the information to backup knowledge check questions.
* Provides the information to backup knowledgecheck questions.
*
* @package qtype_knowledgecheck
* @copyright (c) The Regents of the University of California
Expand Down
3 changes: 3 additions & 0 deletions backup/moodle2/restore_qtype_knowledgecheck_plugin.class.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* Restore plugin for the Knowledge check question type.
*
* @package qtype_knowledgecheck
* @subpackage backup-moodle2
* @copyright (c) The Regents of the University of California
Expand Down Expand Up @@ -51,6 +53,7 @@ protected function define_question_plugin_structure() {

/**
* Process the qtype/knowledgecheck element
* @param array $data The data to restore.
*/
public function process_knowledgecheck($data) {
global $DB;
Expand Down
16 changes: 16 additions & 0 deletions edit_knowledgecheck_form.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,11 @@
*/
class qtype_knowledgecheck_edit_form extends question_edit_form {

/**
* {@inheritdoc}
*
* @param object $mform The form being built.
*/
protected function definition_inner($mform) {
$mform->addElement('editor', 'responsetemplate', get_string('responsetemplate', 'qtype_knowledgecheck'),
['rows' => 10], array_merge($this->editoroptions, ['maxfiles' => 0]));
Expand All @@ -39,6 +44,12 @@ protected function definition_inner($mform) {
['1.0' => '100%'], 1, 0);
}

/**
* {@inheritdoc}
*
* @param object $question The data being passed to the form.
* @return object $question The modified data.
*/
protected function data_preprocessing($question) {
$question = parent::data_preprocessing($question);
$question = $this->data_preprocessing_answers($question);
Expand All @@ -55,6 +66,11 @@ protected function data_preprocessing($question) {
return $question;
}

/**
* {@inheritdoc}
*
* @return string The question type name.
*/
public function qtype() {
return 'knowledgecheck';
}
Expand Down
57 changes: 57 additions & 0 deletions question.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,14 +46,28 @@ class qtype_knowledgecheck_question extends question_graded_by_strategy
*/
public $answers = [];

/**
* {@inheritdoc}
*/
public function __construct() {
parent::__construct(new question_first_matching_answer_grading_strategy($this));
}

/**
* {@inheritdoc}
*
* @return array A structure defining what data is expected in the response to this question.
*/
public function get_expected_data() {
return ['answer' => PARAM_RAW_TRIMMED];
}

/**
* {@inheritdoc}
*
* @param array $response A given response.
* @return string|null A plain text summary of that response, that could be used in reports.
*/
public function summarise_response(array $response) {
if (isset($response['answer'])) {
return $response['answer'];
Expand All @@ -62,24 +76,56 @@ public function summarise_response(array $response) {
}
}

/**
* {@inheritdoc}
*
* @param array $response A list of responses.
* @return bool whether this response is a complete answer to this question.
*/
public function is_complete_response(array $response) {
return array_key_exists('answer', $response) &&
($response['answer'] || $response['answer'] === '0');
}

/**
* {@inheritdoc}
*
* @param array $response The given response
* @return string the validation error message.
*/
public function get_validation_error(array $response) {
return get_string('pleaseenterananswer', 'qtype_knowledgecheck');
}

/**
* {@inheritdoc}
*
* @param array $prevresponse the responses previously recorded for this question.
* @param array $newresponse the new responses, in the same format.
* @return bool whether the two sets of responses are the same - that is
* whether the new set of responses can safely be discarded.
*/
public function is_same_response(array $prevresponse, array $newresponse) {
return question_utils::arrays_same_at_key_missing_is_blank(
$prevresponse, $newresponse, 'answer');
}

/**
* Returns a list of possible answers to this question.
*
* @return array A list of possible answers to this question.
*/
public function get_answers() {
return $this->answers;
}

/**
* Compares the given response with a given possible answer.
*
* @param array $response the response.
* @param question_answer $answer an answer.
* @return bool whether the response matches the answer.
*/
public function compare_response_with_answer(array $response, question_answer $answer) {
if (!array_key_exists('answer', $response) || is_null($response['answer'])) {
return false;
Expand All @@ -89,6 +135,17 @@ public function compare_response_with_answer(array $response, question_answer $a
return true;
}

/**
* {@inheritdoc}
*
* @param question_attempt $qa the question attempt being displayed.
* @param question_display_options $options the options that control display of the question.
* @param string $component the name of the component we are serving files for.
* @param string $filearea the name of the file area.
* @param array $args the remaining bits of the file path.
* @param bool $forcedownload whether the user must be forced to download the file.
* @return bool true if the user can access this file.
*/
public function check_file_access($qa, $options, $component, $filearea,
$args, $forcedownload) {
if ($component == 'question' && $filearea == 'answerfeedback') {
Expand Down
53 changes: 53 additions & 0 deletions questiontype.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,16 +38,36 @@
*/
class qtype_knowledgecheck extends question_type {

/**
* {@inheritdoc}
*
* @param int $questionid the question being moved.
* @param int $oldcontextid the context it is moving from.
* @param int $newcontextid the context it is moving to.
*/
public function move_files($questionid, $oldcontextid, $newcontextid) {
parent::move_files($questionid, $oldcontextid, $newcontextid);
$this->move_files_in_hints($questionid, $oldcontextid, $newcontextid);
}

/**
* {@inheritdoc}
*
* @param int $questionid the question being deleted.
* @param int $contextid the context the question is in.
*/
protected function delete_files($questionid, $contextid) {
parent::delete_files($questionid, $contextid);
$this->delete_files_in_hints($questionid, $contextid);
}

/**
* {@inheritdoc}
*
* @param object $question This holds the information from the editing form,
* it is not a standard question object.
* @return object $result->error or $result->notice
*/
public function save_question_options($question) {
global $DB;
$options = $DB->get_record('qtype_knowledgecheck_options', ['questionid' => $question->id]);
Expand All @@ -63,16 +83,37 @@ public function save_question_options($question) {
$this->save_hints($question);
}

/**
* {@inheritdoc}
*
* @param question_definition $question the question_definition we are creating.
* @param object $questiondata the question data loaded from the database.
*/
protected function initialise_question_instance(question_definition $question, $questiondata) {
parent::initialise_question_instance($question, $questiondata);
$this->initialise_question_answers($question, $questiondata);

}

/**
* {@inheritdoc}
*
* @param stdClass $questiondata data defining a question, as returned by
* question_bank::load_question_data().
* @return number|null either a fraction estimating what the student would
* score by guessing, or null, if it is not possible to estimate.
*/
public function get_random_guess_score($questiondata) {
return 0;
}

/**
* {@inheritdoc}
*
* @param object $questiondata the question definition data.
* @return array keys are subquestionid, values are arrays of possible
* responses to that subquestion.
*/
public function get_possible_responses($questiondata) {
$responses = [];

Expand All @@ -86,10 +127,22 @@ public function get_possible_responses($questiondata) {
return [$questiondata->id => $responses];
}

/**
* {@inheritdoc}
*
* @return mixed array as above, or null to tell the base class to do nothing.
*/
public function extra_question_fields() {
return ['qtype_knowledgecheck_options', 'responsetemplate'];
}

/**
* {@inheritdoc}
*
* @return bool override this to return false if this is not really a
* question type, for example the description question type is not
* really a question type.
*/
public function is_real_question_type() {
return false;
}
Expand Down
53 changes: 50 additions & 3 deletions renderer.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,14 @@
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class qtype_knowledgecheck_renderer extends qtype_renderer {

/**
* {@inheritdoc}
*
* @param question_attempt $qa the question attempt to display.
* @param question_display_options $options controls what should and should not be displayed.
* @return string HTML fragment.
*/
public function formulation_and_controls(question_attempt $qa,
question_display_options $options) {

Expand Down Expand Up @@ -73,6 +81,12 @@ public function formulation_and_controls(question_attempt $qa,
return $result;
}

/**
* {@inheritdoc}
*
* @param question_attempt $qa the question attempt to display.
* @return string HTML fragment.
*/
public function specific_feedback(question_attempt $qa) {
$question = $qa->get_question();

Expand All @@ -86,26 +100,51 @@ public function specific_feedback(question_attempt $qa) {
}
}


/**
* A format renderer for knowledge checks where the student should use the HTML
* editor without the file picker.
* A format renderer for knowledge checks where the student should use the HTML editor without the file picker.
*
* Copied and modified from the Essay question type for our purposes.
*
* @package qtype_knowledgecheck
* @copyright (c) The Regents of the University of California
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class qtype_knowledgecheck_format_editor_renderer extends plugin_renderer_base {

/**
* Gets a specific class name to add to the input element.
*
* @return string specific class name to add to the input element.
*/
protected function class_name() {
return 'qtype_knowledgecheck_editor';
}

/**
* Render the student's response when the question is in read-only mode.
*
* @param string $name the variable name this input edits.
* @param question_attempt $qa the question attempt being display.
* @param question_attempt_step $step the current step.
* @param int $lines approximate size of input box to display.
* @param object $context the context teh output belongs to.
* @return string html to display the response.
*/
public function response_area_read_only($name, $qa, $step, $lines, $context) {
return html_writer::tag('div', $this->prepare_response($name, $qa, $step, $context),
['class' => $this->class_name() . ' qtype_knowledgecheck_editor readonly']);
}

/**
* Render the student's response when the question is in read-only mode.
*
* @param string $name the variable name this input edits.
* @param question_attempt $qa the question attempt being display.
* @param question_attempt_step $step the current step.
* @param int $lines approximate size of input box to display.
* @param object $context the context teh output belongs to.
* @return string html to display the response for editing.
*/
public function response_area_input($name, $qa, $step, $lines, $context) {
global $CFG;
require_once($CFG->dirroot . '/repository/lib.php');
Expand Down Expand Up @@ -155,6 +194,7 @@ public function response_area_input($name, $qa, $step, $lines, $context) {

/**
* Prepare the response for read-only display.
*
* @param string $name the variable name this input edits.
* @param question_attempt $qa the question attempt being display.
* @param question_attempt_step $step the current step.
Expand All @@ -175,6 +215,7 @@ protected function prepare_response($name, question_attempt $qa,

/**
* Prepare the response for editing.
*
* @param string $name the variable name this input edits.
* @param question_attempt_step $step the current step.
* @param object $context the context the attempt belongs to.
Expand All @@ -186,6 +227,8 @@ protected function prepare_response_for_editing($name,
}

/**
* Get editor options for question response text area.
*
* @param object $context the context the attempt belongs to.
* @return array options for the editor.
*/
Expand All @@ -194,6 +237,8 @@ protected function get_editor_options($context) {
}

/**
* Get filepicker options for the editor.
*
* @param object $context the context the attempt belongs to.
* @param int $draftitemid draft item id.
* @return array filepicker options for the editor.
Expand All @@ -203,6 +248,8 @@ protected function get_filepicker_options($context, $draftitemid) {
}

/**
* Get HTML for the filepicker, if used.
*
* @param string $inputname input field name.
* @param int $draftitemid draft file area itemid.
* @return string HTML for the filepicker, if used.
Expand Down

0 comments on commit ba596fe

Please sign in to comment.