Import/export for questiontype plugins

This is implemented from Moodle 1.8.3

Motivation

While it is easy enough to add import and export capability for core questiontypes there is no clear way to allow contributed questiontype authors to enhance their plugin with import and export code. This is an outline proposal for including hooks for that functionality. It is primarily aimed at the Moodle XML format (the most comprehensive import/export format) but with a definite goal not to exclude any other format that may wish to use it.

New Methods in Questiontype Class

The main mechanism for this process will be new methods for import and export to be added to the questiontype class. There would be a discrete method for each supported format type. Note that these will not (and should not) be implemented for core question types.

Import

Implement a method for each import format that you wish to handle in the questiontype class. The naming convention is import_from_format (for example import_from_gift, import_from_xml). The method is responsible for checking the supplied data and returning a question object suitable for the save_question_options() method in the appropriate questiontype class. The method must check in particular that the data is correct for the questiontype and return a false if it is not. This is because import methods will be polled to find one to handle the data, as the correct question type cannot always be established in the general case.

Warning: It is vital that the function makes some sort of check that the question is valid (for this qtype) and returns false if it is not.

The template for one of these methods would be (using import_from_xml as an example) as follows:

   /**
    * Provide import functionality for xml format
    * @param data mixed the segment of data containing the question
    * @param question object question object processed (so far) by standard import code
    * @param format object the format object so that helper methods can be used (in particular error() )
    * @param extra mixed any additional format specific data that may be passed by the format (see format code for info)
    * @return object question object suitable for save_options() call or false if cannot handle
    */
   function import_from_xml( $data, $question, $format, $extra=null ) {
       if ($data->.......
           ....
           return $question;
       }
       else {
           return false;
       }
   } 

Notes:

• The $question parameter will contain whatever the core routines have managed to work out so far
• The $format object is the calling object in case there are any useful methods. In particular this method should call $format->error() to report errors properly

Export

For each export format that your question plugin supports write a method called export_to_format (for example, export_to_gift, export_to_xml). The method simply takes the question object (use print_r() to see what it looks like) and returns a string containing the lines to append to the exported file. Returning false will be regarded as an error condition.

The template for one of these methods (using xml format as an example) could be:

   /**
    * Provide export functionality for xml format
    * @param question object the question object
    * @param format object the format object so that helper methods can be used 
    * @param extra mixed any additional format specific data that may be passed by the format (see format code for info)
    * @return string the data to append to the output buffer or false if error
    */
   function export_to_xml( $question, $format, $extra=null ) {
       ....
       return $xmlquestion;
   }

New methods is qformat_default class (format.php)

Two new methods (one for import and one for export) will be provided for the format plugin to call to handle situations that they cannot handle themselves. These would be called from the format classes in an appropriate place (ie, when they "decide" that they cannot handle the question internally)

Import

As import cannot, in the general sense, matching unhandled question types to the classes (as names may well differ) the installed questiontypes will be polled to find the (first) one that will handle the data. The import/export format should simply call $this->import_plugin() when it is unable to handle the question data itself. It will either return the $question object or false if it fails. The format class retains the responsibility of reporting unhandled question types. This functionality is optional for import/output formats.

  /**
    * Import for questiontype plugins
    * @param data mixed the segment of data containing the question
    * @param question object question object processed (so far) by standard import code
    * @param extra mixed any additional format specific data that may be passed by the format (see format code for info)
    * @return object question object suitable for save_options() call or false if cannot handle
    */
   function try_importing_using_qtypes( $data, $question, $extra=null ) {
       global $QTYPES;
       $formatname = substr(get_class( $this ), length('qformat_'));
       $methodname = "import_from_$formatname";
       foreach ($QTYPES as $qtype) {
           if (method_exists( $qtype, $methodname )) {
               if ($question = $qtype->$methodname( $data, $question, $this, $extra )) {
                   return $question;
               }
           }
       }
       return false;
   }

Export

The export routine simpler, as the questiontype name will always be known. If the export routine encounters a question type that it cannot handle it should call $this->export_plugin(). If the question is handled the function will return a string containing the exported data. If it cannot be handled the function returns false.

   /**
    * Provide export functionality for plugin questiontypes
    * @param name questiontype name
    * @param question object the question object
    * @param extra mixed any additional format specific data that may be passed by the format (see format code for info)
    * @return string the data to append to the output buffer or false if error
    */
   function try_exporting_using_qtypes( $name, $question, $extra=null ) {
       global $QTYPES;
       $formatname = substr(get_class( $this ), length('qformat_'));
       $methodname = "export_to_$formatname";
       if (array_key_exists( $name, $QTYPES )) {
           $qtype = $QTYPES[ $name ];
           if (method_exists( $qtype, $methodname )) {
               if ( $data = $qtype->$methodname( $question, $this, $extra )) {
                   return $data;
               }
           }
       }
       return false;
   }

Error handling

The recommended way for import/export formats to report a syntax error is to call the error() method within the format class. The format object is passed to the questiontype method so that $format->error can be called.

Notes for individual formats

This is currently only implemented for the XML and GIFT formats. These are specific notes about how they are implemented and what to expect in the passed parameters.

See Also

• Discussion
• [https://tracker.moodle.org/browse/MDL-2727 MDL-2727]