Developer Documentation

  • Bug fixes for general core bugs in 3.11.x will end 14 Nov 2022 (12 months plus 6 months extension).
  • Bug fixes for security issues in 3.11.x will end 13 Nov 2023 (18 months plus 12 months extension).
  • PHP version: minimum PHP 7.3.0 Note: minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is supported too.
  • Differences Between: [Versions 310 and 311] [Versions 311 and 400] [Versions 37 and 311] [Versions 38 and 311] [Versions 39 and 311]

    Defines the base class for question import and export formats.

    Copyright: 1999 onwards Martin Dougiamas {@link}
    License: GNU GPL v3 or later
    File Size: 1221 lines (46 kb)
    Included or required:0 times
    Referenced: 15 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/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
    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