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.

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]

Defines the base class for question import and export formats.

Copyright: 1999 onwards Martin Dougiamas {@link http://moodle.com}
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 1239 lines (47 kb)
Included or required:0 times
Referenced: 8 times
Includes or requires: 0 files

Defines 2 classes


Class: qformat_default  - X-Ref

Base class for question import and export formats.

provide_import()   X-Ref
No description

provide_export()   X-Ref
No description

mime_type()   X-Ref
No description

export_file_extension()   X-Ref

return: string the file extension (including .) that is normally used for

can_import_file($file)   X-Ref
Check if the given file is capable of being imported by this plugin.

Note that expensive or detailed integrity checks on the file should
not be performed by this method. Simple file type or magic-number tests
would be suitable.

param: stored_file $file the file to check
return: bool whether this plugin can import the file

validate_file(stored_file $file)   X-Ref
Validate the given file.

For more expensive or detailed integrity checks.

param: stored_file $file the file to check
return: string the error message that occurred while validating the given file

validate_is_utf8_file(stored_file $file)   X-Ref
Check if the given file has the required utf8 encoding.

param: stored_file $file the file to check
return: string the error message if the file encoding is not UTF-8

get_name()   X-Ref
Return the localized pluginname string for the question format.

return: string the pluginname string for the question format

setCategory($category)   X-Ref
set the category

param: object category the category object

setQuestions($questions)   X-Ref
Set the specific questions to export. Should not include questions with
parents (sub questions of cloze question type).
Only used for question export.

param: array of question objects

setCourse($course)   X-Ref
set the course class variable

param: course object Moodle course variable

setContexts($contexts)   X-Ref
set an array of contexts.

param: array $contexts Moodle course variable

setFilename($filename)   X-Ref
set the filename

param: string filename name of file to import/export

setRealfilename($realfilename)   X-Ref
set the "real" filename
(this is what the user typed, regardless of wha happened next)

param: string realfilename name of file as typed by user

setMatchgrades($matchgrades)   X-Ref
set matchgrades

param: string matchgrades error or nearest for grades

setCatfromfile($catfromfile)   X-Ref
set catfromfile

param: bool catfromfile allow categories embedded in import file

setContextfromfile($contextfromfile)   X-Ref
set contextfromfile

param: bool $contextfromfile allow contexts embedded in import file

setCattofile($cattofile)   X-Ref
set cattofile

param: bool cattofile exports categories within export file

setContexttofile($contexttofile)   X-Ref
set contexttofile

param: bool cattofile exports categories within export file

setStoponerror($stoponerror)   X-Ref
set stoponerror

param: bool stoponerror stops database write if any errors reported

set_can_access_backupdata($canaccess)   X-Ref

param: bool $canaccess Whether the current use can access the backup data folder. Determines

set_display_progress($displayprogress)   X-Ref
Change whether to display progress messages.
There is normally no need to use this function as the
default for $displayprogress is true.
Set to false for unit tests.

param: bool $displayprogress

error($message, $text='', $questionname='')   X-Ref
Handle parsing error


try_importing_using_qtypes($data, $question = null, $extra = null,$qtypehint = '')   X-Ref
Import for questiontype plugins
Do not override.

param: data mixed The segment of data containing the question
param: question object processed (so far) by standard import code if appropriate
param: extra mixed any additional format specific data that may be passed by the format
param: qtypehint hint about a question type from format
return: object question object suitable for save_options() or false if cannot handle

importpreprocess()   X-Ref
Perform any required pre-processing

return: bool success

importprocess()   X-Ref
Process the file
This method should not normally be overidden

return: bool success

count_questions($questions)   X-Ref
Count all non-category questions in the questions array.

param: array questions An array of question objects.
return: int The count.

create_category_path($catpath, $lastcategoryinfo = null)   X-Ref
find and/or create the category described by a delimited list
e.g. $course$/tom/dick/harry or tom/dick/harry

removes any context string no matter whether $getcontext is set
but if $getcontext is set then ignore the context and use selected category context.

param: string catpath delimited category path
param: object $lastcategoryinfo Contains category information
return: mixed category object or null if fails

readdata($filename)   X-Ref
Return complete file within an array, one item per line

param: string filename name of file
return: mixed contents array or false on failure

readquestions($lines)   X-Ref
Parses an array of lines into an array of questions,
where each item is a question object as defined by
readquestion().   Questions are defined as anything
between blank lines.

NOTE this method used to take $context as a second argument. However, at
the point where this method was called, it was impossible to know what
context the quetsions were going to be saved into, so the value could be
wrong. Also, none of the standard question formats were using this argument,
so it was removed. See MDL-32220.

If your format does not use blank lines as a delimiter
then you will need to override this method. Even then
try to use readquestion for each question
param: array lines array of lines from readdata
return: array array of question objects

defaultquestion()   X-Ref
return an "empty" question
Somewhere to specify question parameters that are not handled
by import but are required db fields.
This should not be overridden.

return: object default question

create_default_question_name($questiontext, $default)   X-Ref
Construct a reasonable default question name, based on the start of the question text.

param: string $questiontext the question text.
param: string $default default question name to use if the constructed one comes out blank.
return: string a reasonable question name.

clean_question_name($name)   X-Ref
Ensure that a question name does not contain anything nasty, and will fit in the DB field.

param: string $name the raw question name.
return: string a safe question name.

add_blank_combined_feedback($question)   X-Ref
Add a blank combined feedback to a question object.

param: object question
return: object question

readquestion($lines)   X-Ref
Given the data known to define a question in
this format, this function converts it into a question
object suitable for processing and insertion into Moodle.

If your format does not use blank lines to delimit questions
(e.g. an XML format) you must override 'readquestions' too
param: $lines mixed data that represents question
return: object question object

importpostprocess()   X-Ref
Override if any post-processing is required

return: bool success

try_exporting_using_qtypes($name, $question, $extra=null)   X-Ref
Provide export functionality for plugin questiontypes
Do not override

param: name questiontype name
param: question object data to export
param: extra mixed any addition format specific data needed
return: string the data to append to export or false if error (or unhandled)

exportpreprocess()   X-Ref
Do any pre-processing that may be required

param: bool success

presave_process($content)   X-Ref
Enable any processing to be done on the content
just prior to the file being saved
default is to do nothing

param: string output text
param: string processed output text

exportprocess($checkcapabilities = true)   X-Ref
Perform the export.
For most types this should not need to be overrided.

param: bool    $checkcapabilities Whether to check capabilities when exporting the questions.
return: string  The content of the export.

create_dummy_question_representing_category(string $categoryname, $categoryinfo)   X-Ref
Create 'dummy' question for category export.

param: string $categoryname the name of the category
param: object $categoryinfo description of the category
return: stdClass 'dummy' question for category

get_category_path($id, $includecontext = true)   X-Ref
get the category as a path (e.g., tom/dick/harry)

param: int id the id of the most nested catgory
return: string the path

assemble_category_path($names)   X-Ref
Convert a list of category names, possibly preceeded by one of the
context tokens like $course$, into a string representation of the
category path.

Names are separated by / delimiters. And /s in the name are replaced by //.

To reverse the process and split the paths into names, use
{@link split_category_path()}.

param: array $names
return: string

split_category_path($path)   X-Ref
Convert a string, as returned by {@link assemble_category_path()},
back into an array of category names.

Each category name is cleaned by a call to clean_param(, PARAM_TEXT),
which matches the cleaning in question/bank/managecategories/category_form.php.

param: string $path
return: array of category names.

exportpostprocess()   X-Ref
Do an post-processing that may be required

return: bool success

writequestion($question)   X-Ref
convert a single question object into text output in the given
format.
This must be overriden

param: object question question object
return: mixed question export text or null if not implemented

format_question_text($question)   X-Ref
Convert the question text to plain text, so it can safely be displayed
during import to let the user see roughly what is going on.


Class: qformat_based_on_xml  - X-Ref

cleaninput($str)   X-Ref
A lot of imported files contain unwanted entities.
This method tries to clean up all known problems.

param: string str string to correct
return: string the corrected string

text_field($text)   X-Ref
Return the array moodle is expecting
for an HTML text. No processing is done on $text.
qformat classes that want to process $text
for instance to import external images files
and recode urls in $text must overwrite this method.

param: array $text some HTML text string
return: array with keys text, format and files.

getpath($xml, $path, $default, $istext=false, $error='')   X-Ref
Return the value of a node, given a path to the node
if it doesn't exist return the default value.

param: array xml data to read
param: array path path to node expressed as array
param: mixed default
param: bool istext process as text
param: string error if set value must exist, return false and issue message if not
return: mixed value