OpenDb Import documentation
---------------------------

1)	Introduction

There are currently three different types of plugins supported:

	Row based
	XML based

Each of different types of plugins support a different
function structure, in the plugin script.

All plugins must be located under the import/ subdirectory of
the OpenDb distribution.  They should be descriptively named,
and used '_' in the file name to indicate spaces in words,
as this is how they will be titled, when in use.

2)	Plugin architecture

	Every import plugin should include a class attribute $classname,
	which matches the name of the class:
		// required for introspection
		var $classname = 'CSV';
	
	There is one common function each plugin class provides:
		get_plugin_type()
			This should return 'xml', 'row'
			
	Return an english display name.  Currently no language support
	in these plugins, although plugin writers can lookup the
	$OPENDB_LANGUAGE variable and return a value appropriate to the
	current language, if they want to.
		get_display_name()
	
	For 'row' plugins, the following function should be provided.
		is_extension_supported($extension)
	
	For 'xml' plugins, the DOCTYPE will be parsed to work out what
	plugin to use, so 'xml' plugins must provide the 
		is_doctype_supported($doctype)
	
	The class name should match the name of the php file name (this
	match is case-sensitive), minus the .php extension of course.
	
	For example, if I have a plugin file 'OpenDb_XML.php', the
	class name should be 'class OpenDb_XML'

3)	Plugin Structure

A description of each plugin type

3.1)	Row based

	/**
	* @return TRUE if specified $extension is valid for this
	* plugin.
	*/
	function is_extension_supported($extension)

	/*
	* Indicates that read_header(&$fileHandler) will actually
	* return the first row of data, that would normally be read
	* from read_row(...) if read_header(...) were not called first.
	*/
	function is_header_row()
	
	/*
	* @return a array of strings representing the header
	* columns.
	*/
	function read_header(&$fileHandler, &$error)
	
	/*
	* @return a array of columns values for the current row.  Once
	* this function has finished the &$fileHandler will have moved
	* to the start of the next row.  Returns FALSE if no data can
	* be read from &$fileHandler.
	* 
	* Allows the plugin to filter on $s_item_type, $owner_id if
	* required.
	*/
	function read_row(&$fileHandler, &$error)
	
3.2)	XML based

	The valid extension needs to be 'xml' for all XML imports, and the doctype
	will be parsed to ascertain which plugin to use.
	
	Will parse a complete OpenDb item, including item, instance(s), attribute(s) and linked item(s) 
	(including any linked item attributes) via a series of callback functions:
	
		function import_start_item($s_item_type, $title = NULL, $category = NULL)
		function import_set_title($title)
		function import_set_category($category)
		function import_item_instance($s_status_type = NULL, $status_comment = NULL, $borrow_duration = NULL)
		function import_item_attribute($s_attribute_type, $order_no, $attribute_val)
		function import_end_item()
	
	It is up to the plugin to map the structure of the file being parsed to match
	what is required in the callbacks.  The plugin script, can record state details
	in global variables, as they will only be accessed from the read_item function.
	The read_item function will be called, and the calling process will wait for it
	to finish, and then call it again, until it returns FALSE.
	
	/*
	Check doctype to ensure we support it in this plugin.
	*/
	function is_doctype_supported($doctype)
	
	/**
	@param $itemImportHandler
	@param $name	The name of the tag.
	@param $attribs	An array of all attributes, whether they have a value or not.
	@param $pcdata	Any PCDATA for the attribute.  This avoid having to
					implement a characters function as well.
	*/
	function start_element($name, $attribs, $pcdata)
	{
	}
	
	/**
	@param $itemImportHandler
	@param $name	The name of the tag.
	*/
	function end_element($name)
	{
	}

4)	Windows 'file_upload = Off' issue

	On Windows with IIS 5 (I have not tried with Apache on windows), if
	file_upload = Off, and you attempt to do a file upload, scripts that perform
	file uploads will misbehave badly.  This is because no HTTP parameters 
	will actually get through to the script.  Linux with Apache on the other hand,
	will send all but the FILE HTTP_POST_FILES array information, which
	will result in slightly better behaviour and better error information.

	So if you want to do file uploads, ensure that the 'file_upload' variable is 
	set to true.
