Import_Plugins

Table of Contents Introduction Plugin architecture Plugin Structure Row based XML based Windows 'file_upload = Off' issue

Introduction

There are currently two different types of plugins supported:

• Row based
• XML based

Each type of plugin supports a different function structure.

All plugins must be located under the import/ subdirectory of the OpenDb distribution.

Plugin architecture

• 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: is_doctype_supported($doctype)
• For 'xml' plugins, the namespace will be parsed to determin what plugin to use, 'xml' plugins should provide: is_namespace_supported($nameSpace). However this function is not compulsory.
• 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 'OpenDb_XML'.

Plugin Structure

In the following a description of each plugin type:

Row based

/**
* @return display name of plugin for UI
*/
function get_display_name()

/**
* @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)

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:

• $this->startItem($s_item_type)
• $this->setTitle($title)
• $this->startItemInstance()
• $this->setInstanceStatusType($statusType)
• $this->setInstanceBorrowDuration($borrowDuration)
• $this->setInstanceStatusComment($statusComment)
• $this->addAttribute($attributeType, $attributeValue)
• $this->endItem()
• $this->endItemInstance()

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)

/*
Check namespace to ensure we support it in this plugin.
*/
function is_namespace_supported($nameSpace)

/**
@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)

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 $_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 php.ini 'file_upload' variable is set to true.