qformat_blackboard_six_pool Class Reference

Blackboard pool question importer class. More...

Inheritance diagram for qformat_blackboard_six_pool:

Public Member Functions
	can_import_file ($file)
	Check if the given file is capable of being imported by this plugin.
	clean_question_name ($name)
	Ensure that a question name does not contain anything nasty, and will fit in the DB field.
	clean_question_name ($name)
	Ensure that a question name does not contain anything nasty, and will fit in the DB field.
	cleaned_text_field ($text)
	Same as text_field but text is cleaned.
	cleaninput ($str)
	A lot of imported files contain unwanted entities.
	cleaninput ($str)
	A lot of imported files contain unwanted entities.
	create_default_question_name ($questiontext, $default)
	Construct a reasonable default question name, based on the start of the question text.
	create_default_question_name ($questiontext, $default)
	Construct a reasonable default question name, based on the start of the question text.
	export_file_extension ()
	exportpreprocess ()
	Do any pre-processing that may be required.
	exportprocess ($checkcapabilities=true)
	Perform the export.
	getpath ($xml, $path, $default, $istext=false, $error='')
	Return the value of a node, given a path to the node if it doesn't exist return the default value.
	getpath ($xml, $path, $default, $istext=false, $error='')
	Return the value of a node, given a path to the node if it doesn't exist return the default value.
	importpostprocess ()
	Does any post-processing that may be desired Clean the temporary directory if a zip file was imported.
	importpreprocess ()
	importpreprocess ()
	Perform any required pre-processing.
	importprocess ($filename, $lesson, $pageid)
	importprocess ()
	Process the file This method should not normally be overidden.
	mime_type ()
	The string mime-type of the files that this plugin reads or writes.
	process_category ($xml, &$questions)
	Add a category question entry based on the pool file title.
	process_common ($questiondata)
	Do question import processing common to every qtype.
	process_essay ($xml, &$questions)
	Process Essay Questions.
	process_fib ($xml, &$questions)
	Process Fill in the Blank Questions.
	process_ma ($xml, &$questions)
	Process Multiple Choice Questions With Multiple Answers.
	process_matching ($xml, &$questions)
	Process Matching Questions.
	process_mc ($xml, &$questions)
	Process Multiple Choice Questions with single answer.
	process_tf ($xml, &$questions)
	Process True / False Questions.
	provide_export ()
	provide_import ()
	This plugin provide import.
	readdata ($filename)
	set_can_access_backupdata ($canaccess)
	set_display_progress ($displayprogress)
	Change whether to display progress messages.
	set_filebase ($path)
	Set the path to the root of images tree.
	set_importcontext ($context)
	setCategory ($category)
	set the category
	setCatfromfile ($catfromfile)
	set catfromfile
	setCattofile ($cattofile)
	set cattofile
	setContextfromfile ($contextfromfile)
	set contextfromfile
	setContexts ($contexts)
	set an array of contexts.
	setContexttofile ($contexttofile)
	set contexttofile
	setCourse ($course)
	set the course class variable
	setFilename ($filename)
	set the filename
	setMatchgrades ($matchgrades)
	set matchgrades
	setQuestions ($questions)
	Set the specific questions to export.
	setRealfilename ($realfilename)
	set the "real" filename (this is what the user typed, regardless of wha happened next)
	setStoponerror ($stoponerror)
	set stoponerror
	text_field ($text)
	Given an HTML text with references to images files, store all images in a draft filearea, and return an array with all urls in text recoded, format set to FORMAT_HTML, and itemid set to filearea itemid.
	try_importing_using_qtypes ($data, $question=null, $extra=null, $qtypehint='')
	Import for questiontype plugins.
	try_importing_using_qtypes ($data, $question=null, $extra=null, $qtypehint='')
	Import for questiontype plugins Do not override.
	validate_file (stored_file $file)
	Validate the given file.

Public Attributes
	$canaccessbackupdata = true
	$category = null
	$catfromfile = 0
	$cattofile = 0
	$contextfromfile = 0
context[]	$contexts
	$contexttofile = 0
	$course = null
	$displayerrors = true
bool	$displayprogress = true
	$displayprogress Whether to display progress.
string	$filebase = ''
	path to path to root of image tree in unzipped archive.
	$filename = ''
	$importerrors = 0
bool	$ishtml = true
	Is the current question's question text escaped HTML (true for most if not all Blackboard files).
	$matchgrades = 'error'
	$qtypeconvert
	$questionids = array()
	$questions = array()
	$realfilename = ''
	$stoponerror = true
string	$tempdir = ''
	path to the temporary directory.
	$translator = null

Protected Member Functions
	add_blank_combined_feedback ($question)
	Since the lesson module tries to re-use the question bank import classes in a crazy way, this is necessary to stop things breaking.
	add_blank_combined_feedback ($question)
	Add a blank combined feedback to a question object.
	assemble_category_path ($names)
	Convert a list of category names, possibly preceeded by one of the context tokens like $course$, into a string representation of the category path.
	count_questions ($questions)
	Count all non-category questions in the questions array.
	count_questions ($questions)
	Count all non-category questions in the questions array.
	create_category_path ($catpath, $lastcategoryinfo=null)
	find and/or create the category described by a delimited list e.g.
	create_dummy_question_representing_category (string $categoryname, $categoryinfo)
	Create 'dummy' question for category export.
	defaultquestion ()
	return an "empty" question Somewhere to specify question parameters that are not handled by import but are required db fields.
	defaultquestion ()
	return an "empty" question Somewhere to specify question parameters that are not handled by import but are required db fields.
	error ($message, $text='', $questionname='')
	Handle parsing error.
	error ($message, $text='', $questionname='')
	Handle parsing error.
	exportpostprocess ()
	Do an post-processing that may be required.
	format_question_text ($question)
	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.
	format_question_text ($question)
	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.
	get_category_path ($id, $includecontext=true)
	get the category as a path (e.g., tom/dick/harry)
	get_name ()
	Return the localized pluginname string for the question format.
	presave_process ($content)
	Enable any processing to be done on the content just prior to the file being saved default is to do nothing.
	readdata ($filename)
	Return complete file within an array, one item per line.
	readquestion ($lines)
	readquestion ($lines)
	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.
	readquestions ($text)
	Parse the xml document into an array of questions.
	split_category_path ($path)
	Convert a string, as returned by assemble_category_path(), back into an array of category names.
	store_file_for_text_field (&$text, $tempdir, $filepathinsidetempdir, $filename)
	Store an image file in a draft filearea.
	try_exporting_using_qtypes ($name, $question, $extra=null)
	Provide export functionality for plugin questiontypes Do not override.
	validate_is_utf8_file (stored_file $file)
	Check if the given file has the required utf8 encoding.
	writequestion ($question)
	convert a single question object into text output in the given format.

Protected Attributes
	$importcontext = null

Detailed Description

Blackboard pool question importer class.

Copyright

2003 Scott Elliott

License

http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Member Function Documentation

add_blank_combined_feedback()

qformat_default::add_blank_combined_feedback ( $question )

protectedinherited

Add a blank combined feedback to a question object.

Parameters

object

question

Return values

object

question

assemble_category_path()

qformat_default::assemble_category_path ( $names )

protectedinherited

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 split_category_path().

Parameters

array

$names

Return values

string

can_import_file()

qformat_blackboard_six_base::can_import_file ( $file )

inherited

Check if the given file is capable of being imported by this plugin.

As file_storage::mimetype() may use finfo PHP extension if available, the value returned by $file->get_mimetype for a .dat file is not the same on all servers. So we must made 2 checks to verify if the plugin can import the file.

Parameters

stored_file

$file

the file to check

Return values

bool	whether this plugin can import the file

Reimplemented from qformat_default.

clean_question_name() [1/2]

qformat_default::clean_question_name ( $name )

inherited

Ensure that a question name does not contain anything nasty, and will fit in the DB field.

Parameters

string

$name

the raw question name.

Return values

string

a safe question name.

clean_question_name() [2/2]

qformat_default::clean_question_name ( $name )

inherited

Ensure that a question name does not contain anything nasty, and will fit in the DB field.

Parameters

string

$name

the raw question name.

Return values

string

a safe question name.

cleaned_text_field()

qformat_blackboard_six_base::cleaned_text_field ( $text )

inherited

Same as text_field but text is cleaned.

Parameters

string

$text

text to parse and recode

Return values

array

with keys text, format, itemid.

cleaninput() [1/2]

qformat_based_on_xml::cleaninput ( $str )

inherited

A lot of imported files contain unwanted entities.

This method tries to clean up all known problems.

Parameters

string

str string to correct

Return values

string

the corrected string

cleaninput() [2/2]

qformat_based_on_xml::cleaninput ( $str )

inherited

A lot of imported files contain unwanted entities.

This method tries to clean up all known problems.

Parameters

string

str string to correct

Return values

string

the corrected string

count_questions() [1/2]

qformat_default::count_questions ( $questions )

protectedinherited

Count all non-category questions in the questions array.

Parameters

array

questions An array of question objects.

Return values

int	The count.

count_questions() [2/2]

qformat_default::count_questions ( $questions )

protectedinherited

Count all non-category questions in the questions array.

Parameters

array

questions An array of question objects.

Return values

int	The count.

create_category_path()

qformat_default::create_category_path ( $catpath, $lastcategoryinfo = null )

protectedinherited

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.

Parameters

	string	catpath delimited category path
object	$lastcategoryinfo	Contains category information

Return values

mixed

category object or null if fails

create_default_question_name() [1/2]

qformat_default::create_default_question_name ( $questiontext, $default )

inherited

Construct a reasonable default question name, based on the start of the question text.

Parameters

string	$questiontext	the question text.
string	$default	default question name to use if the constructed one comes out blank.

Return values

string

a reasonable question name.

create_default_question_name() [2/2]

qformat_default::create_default_question_name ( $questiontext, $default )

inherited

Construct a reasonable default question name, based on the start of the question text.

Parameters

string	$questiontext	the question text.
string	$default	default question name to use if the constructed one comes out blank.

Return values

string

a reasonable question name.

create_dummy_question_representing_category()

qformat_default::create_dummy_question_representing_category ( string $categoryname, $categoryinfo )

protectedinherited

Create 'dummy' question for category export.

Parameters

string	$categoryname	the name of the category
object	$categoryinfo	description of the category

Return values

stdClass

'dummy' question for category

defaultquestion() [1/2]

qformat_default::defaultquestion ( )

protectedinherited

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 values

object

default question

defaultquestion() [2/2]

qformat_default::defaultquestion ( )

protectedinherited

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 values

object

default question

error()

qformat_default::error ( $message, $text = '', $questionname = '' )

protectedinherited

Handle parsing error.

Parameters

string	$message	information about error
string	$text	imported text that triggered the error
string	$questionname	imported question name

export_file_extension()

qformat_default::export_file_extension ( )

inherited

Return values

string

the file extension (including .) that is normally used for files handled by this plugin.

Reimplemented in qformat_gift, and qformat_xml.

exportpostprocess()

qformat_default::exportpostprocess ( )

protectedinherited

Do an post-processing that may be required.

Return values

bool

success

exportpreprocess()

qformat_default::exportpreprocess ( )

inherited

Do any pre-processing that may be required.

Parameters

bool

success

Reimplemented in qformat_aiken.

exportprocess()

qformat_default::exportprocess ( $checkcapabilities = true )

inherited

Perform the export.

For most types this should not need to be overrided.

Parameters

bool

$checkcapabilities

Whether to check capabilities when exporting the questions.

Return values

string

The content of the export.

get_category_path()

qformat_default::get_category_path ( $id, $includecontext = true )

protectedinherited

get the category as a path (e.g., tom/dick/harry)

Parameters

int	id the id of the most nested catgory

Return values

string

the path

get_name()

qformat_default::get_name ( )

protectedinherited

Return the localized pluginname string for the question format.

Return values

string

the pluginname string for the question format

getpath() [1/2]

qformat_based_on_xml::getpath ( $xml, $path, $default, $istext = false, $error = '' )

inherited

Return the value of a node, given a path to the node if it doesn't exist return the default value.

Parameters

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

Return values

mixed

value

getpath() [2/2]

qformat_based_on_xml::getpath ( $xml, $path, $default, $istext = false, $error = '' )

inherited

Return the value of a node, given a path to the node if it doesn't exist return the default value.

Parameters

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

Return values

mixed

value

importpostprocess()

qformat_blackboard_six_base::importpostprocess ( )

inherited

Does any post-processing that may be desired Clean the temporary directory if a zip file was imported.

Return values

bool

success

Reimplemented from qformat_default.

importpreprocess()

qformat_default::importpreprocess ( )

inherited

Perform any required pre-processing.

Return values

bool

success

importprocess()

qformat_default::importprocess ( )

inherited

Process the file This method should not normally be overidden.

Return values

bool

success

mime_type()

qformat_blackboard_six_base::mime_type ( )

inherited

The string mime-type of the files that this plugin reads or writes.

Reimplemented from qformat_default.

presave_process()

qformat_default::presave_process ( $content )

protectedinherited

Enable any processing to be done on the content just prior to the file being saved default is to do nothing.

Parameters

string	output text
string	processed output text

Reimplemented in qformat_xml.

process_category()

qformat_blackboard_six_pool::process_category	(		$xml,
		&	$questions )

Add a category question entry based on the pool file title.

Parameters

array	$xml	the xml tree
array	$questions	the questions already parsed

process_common()

qformat_blackboard_six_pool::process_common

(

$questiondata

)

Do question import processing common to every qtype.

Parameters

array

$questiondata

the xml tree related to the current question

Return values

object

initialized question object.

process_essay()

qformat_blackboard_six_pool::process_essay	(		$xml,
		&	$questions )

Process Essay Questions.

Parameters

array	$xml	the xml tree
array	$questions	the questions already parsed

process_fib()

qformat_blackboard_six_pool::process_fib	(		$xml,
		&	$questions )

Process Fill in the Blank Questions.

Parameters

array	$xml	the xml tree
array	$questions	the questions already parsed

process_ma()

qformat_blackboard_six_pool::process_ma	(		$xml,
		&	$questions )

Process Multiple Choice Questions With Multiple Answers.

Parameters

array	$xml	the xml tree
array	$questions	the questions already parsed

process_matching()

qformat_blackboard_six_pool::process_matching	(		$xml,
		&	$questions )

Process Matching Questions.

Parameters

array	$xml	the xml tree
array	$questions	the questions already parsed

process_mc()

qformat_blackboard_six_pool::process_mc	(		$xml,
		&	$questions )

Process Multiple Choice Questions with single answer.

Parameters

array	$xml	the xml tree
array	$questions	the questions already parsed

process_tf()

qformat_blackboard_six_pool::process_tf	(		$xml,
		&	$questions )

Process True / False Questions.

Parameters

array	$xml	the xml tree
array	$questions	the questions already parsed

provide_export()

qformat_default::provide_export ( )

inherited

Return values

bool	whether this plugin provides export functionality.

Reimplemented in qformat_aiken, qformat_gift, and qformat_xml.

provide_import()

qformat_blackboard_six_base::provide_import ( )

inherited

This plugin provide import.

Return values

bool

true

Reimplemented from qformat_default.

readdata() [1/2]

qformat_default::readdata ( $filename )

inherited

Reimplemented in qformat_blackboard_six.

readdata() [2/2]

qformat_default::readdata ( $filename )

protectedinherited

Return complete file within an array, one item per line.

Parameters

string

filename name of file

Return values

mixed

contents array or false on failure

Reimplemented in qformat_blackboard_six.

readquestion()

qformat_default::readquestion ( $lines )

protectedinherited

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

Parameters

$lines

mixed data that represents question

Return values

object

question object

readquestions()

qformat_blackboard_six_pool::readquestions ( $text )

protected

Parse the xml document into an array of questions.

This could burn memory - but it won't happen that much so fingers crossed!

Parameters

array

$text

array of lines from the input file.

Return values

array

(of objects) questions objects.

Reimplemented from qformat_default.

set_can_access_backupdata()

qformat_default::set_can_access_backupdata ( $canaccess )

inherited

Parameters

bool

$canaccess

Whether the current use can access the backup data folder. Determines where export files are saved.

set_display_progress()

qformat_default::set_display_progress ( $displayprogress )

inherited

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.

Parameters

bool

$displayprogress

set_filebase()

qformat_blackboard_six_base::set_filebase ( $path )

inherited

Set the path to the root of images tree.

Parameters

string

$path

path to images root

setCategory()

qformat_default::setCategory ( $category )

inherited

set the category

Parameters

object

category the category object

setCatfromfile()

qformat_default::setCatfromfile ( $catfromfile )

inherited

set catfromfile

Parameters

bool	catfromfile allow categories embedded in import file

setCattofile()

qformat_default::setCattofile ( $cattofile )

inherited

set cattofile

Parameters

bool	cattofile exports categories within export file

setContextfromfile()

qformat_default::setContextfromfile ( $contextfromfile )

inherited

set contextfromfile

Parameters

bool

$contextfromfile

allow contexts embedded in import file

setContexts()

qformat_default::setContexts ( $contexts )

inherited

set an array of contexts.

Parameters

context[]

$contexts

setContexttofile()

qformat_default::setContexttofile ( $contexttofile )

inherited

set contexttofile

Parameters

bool	cattofile exports categories within export file

setCourse()

qformat_default::setCourse ( $course )

inherited

set the course class variable

Parameters

course

object Moodle course variable

setFilename()

qformat_default::setFilename ( $filename )

inherited

set the filename

Parameters

string

filename name of file to import/export

setMatchgrades()

qformat_default::setMatchgrades ( $matchgrades )

inherited

set matchgrades

Parameters

string

matchgrades error or nearest for grades

setQuestions()

qformat_default::setQuestions ( $questions )

inherited

Set the specific questions to export.

Should not include questions with parents (sub questions of cloze question type). Only used for question export.

Parameters

array

of question objects

setRealfilename()

qformat_default::setRealfilename ( $realfilename )

inherited

set the "real" filename (this is what the user typed, regardless of wha happened next)

Parameters

string

realfilename name of file as typed by user

setStoponerror()

qformat_default::setStoponerror ( $stoponerror )

inherited

set stoponerror

Parameters

bool	stoponerror stops database write if any errors reported

split_category_path()

qformat_default::split_category_path ( $path )

protectedinherited

Convert a string, as returned by 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.

Parameters

string

$path

Return values

array

of category names.

store_file_for_text_field()

qformat_blackboard_six_base::store_file_for_text_field ( & $text, $tempdir, $filepathinsidetempdir, $filename )

protectedinherited

Store an image file in a draft filearea.

Parameters

array	$text,if	itemid element don't exists it will be created
string	$tempdir	path to root of image tree
string	$filepathinsidetempdir	path to image in the tree
string	$filename	image's name

Return values

string

new name of the image as it was stored

text_field()

qformat_blackboard_six_base::text_field ( $text )

inherited

Given an HTML text with references to images files, store all images in a draft filearea, and return an array with all urls in text recoded, format set to FORMAT_HTML, and itemid set to filearea itemid.

Parameters

string

$text

text to parse and recode

Return values

array

with keys text, format, itemid.

Reimplemented from qformat_based_on_xml.

try_exporting_using_qtypes()

qformat_default::try_exporting_using_qtypes ( $name, $question, $extra = null )

protectedinherited

Provide export functionality for plugin questiontypes Do not override.

Parameters

name	questiontype name
question	object data to export
extra	mixed any addition format specific data needed

Return values

string

the data to append to export or false if error (or unhandled)

try_importing_using_qtypes() [1/2]

qformat_default::try_importing_using_qtypes ( $data, $question = null, $extra = null, $qtypehint = '' )

inherited

Import for questiontype plugins.

Parameters

mixed	$data	The segment of data containing the question
object	$question	processed (so far) by standard import code if appropriate
object	$extra	mixed any additional format specific data that may be passed by the format
string	$qtypehint	hint about a question type from format

Return values

object

question object suitable for save_options() or false if cannot handle

try_importing_using_qtypes() [2/2]

qformat_default::try_importing_using_qtypes ( $data, $question = null, $extra = null, $qtypehint = '' )

inherited

Import for questiontype plugins Do not override.

Parameters

data	mixed The segment of data containing the question
question	object processed (so far) by standard import code if appropriate
extra	mixed any additional format specific data that may be passed by the format
qtypehint	hint about a question type from format

Return values

object

question object suitable for save_options() or false if cannot handle

validate_file()

qformat_default::validate_file ( stored_file $file )

inherited

Validate the given file.

For more expensive or detailed integrity checks.

Parameters

stored_file

$file

the file to check

Return values

string

the error message that occurred while validating the given file

Reimplemented in qformat_aiken, qformat_gift, qformat_missingword, qformat_multianswer, and qformat_xml.

validate_is_utf8_file()

qformat_default::validate_is_utf8_file ( stored_file $file )

protectedinherited

Check if the given file has the required utf8 encoding.

Parameters

stored_file

$file

the file to check

Return values

string

the error message if the file encoding is not UTF-8

writequestion()

qformat_default::writequestion ( $question )

protectedinherited

convert a single question object into text output in the given format.

This must be overriden

Parameters

object

question question object

Return values

mixed

question export text or null if not implemented

Reimplemented in qformat_aiken, qformat_gift, and qformat_xml.

Member Data Documentation

$qtypeconvert

qformat_default::$qtypeconvert

inherited

Initial value:

= array('numerical'   => LESSON_PAGE_NUMERICAL,
                               'multichoice' => LESSON_PAGE_MULTICHOICE,
                               'truefalse'   => LESSON_PAGE_TRUEFALSE,
                               'shortanswer' => LESSON_PAGE_SHORTANSWER,
                               'match'       => LESSON_PAGE_MATCHING,
                               'essay'       => LESSON_PAGE_ESSAY
                              )

---

The documentation for this class was generated from the following file:

• question/format/blackboard_six/formatpool.php