/**
*
* Prepares data to be imported into the table. It takes raw data and produces an array of
* Dataface_Record objects that can be imported into the table.
*
* @param $data Raw data that is to be imported.
* @type raw
*
* @param $importFilter The name of the import filter that is used to import the data.
* If this is null then every import filter is attempted until one is
* found that works.
* @type string | null
*
* @return An array of Dataface_Record objects encapsulating the imported data. These objects
* must be records of the current table.
*
* @throws PEAR_Error if the importing fails for some reason.
*
* Usage:
* -------
*
* $data = '<phonelist>
* <listentry>
* <name>John Smith</name><number>555-555-5555</number>
* </listentry>
* <listentry>
* <name>Susan Moore</name><number>444-444-4444</number>
* </listentry>
* </phonelist>';
*
* // assume that we have an import filter called 'XML_Filter' that can import the above data.
*
* $table =& Dataface_Table::loadTable('ListEntry');
* $records = $table->parseImportData( $data, // The raw data to import
* 'XML_Filter' // The name of the filter to handle the import
* );
*
* echo get_class($records[0]); // outputs 'Dataface_Record'
* echo $records[0]->val('name'); //outputs 'John Smith'
* echo $records[0]->val('number'); // outputs '555-555-5555'
* echo $records[1]->val('name'); // outputs 'Susan Moore'
* echo $records[1]->val('number'); // outputs '444-444-4444'
*
* // Note that the records in the $records array are NOT persisted in the database.
*
* @see Dataface_Table.loadTable()
* @see Dataface_Table.getImportFilters()
* @see Dataface_Record.val()
*
*/
function parseImportData($data, $importFilter = null, $defaultValues = array())
{
$filters =& $this->getImportFilters();
$delegate =& $this->getDelegate();
if ($delegate === null) {
/*
* Currently the only place that Import filters can be defined is in the
* delegate file. If there is no delegate file, then there are no filters.
* if there are no filters, then we can't possibly do any importing so we
* return an error.
*/
return Dataface_Error::noImportFiltersFound();
}
$errors = array();
if ($importFilter === null) {
/*
* The filter is not specified so we will try every filter until we find one
* that works.
*/
foreach (array_keys($filters) as $filtername) {
$parsed =& $filters[$filtername]->import($data, $defaultValues);
if (PEAR::isError($parsed)) {
/*
* This filter encountered an error.
* Record the error, and unset the $parsed variable.
*/
$errors[$filtername] =& $parsed;
unset($parsed);
continue;
}
break;
}
if (isset($parsed)) {
/*
* The only way that the $parsed variable should be 'set' is if
* one of the filters successfully parsed the data.
*/
return $parsed;
} else {
return Dataface_Error::noImportFiltersFound("No suitable import filter was found to import data into table '" . $this->tablename . "'. The following filters were attempted: {" . implode(',', array_keys($errors)) . "}.");
}
} else {
/*
* A particular import filter was specified so we will try with that one.
*/
if (!isset($filters[$importFilter])) {
return Dataface_Error::noImportFiltersFound("The import filter '" . $importFilter . "' was not found while attempting to import data into the table '" . $this->tablename . "'. The following import filters are available: {" . implode(',', array_keys($errors)) . "}.");
}
return $filters[$importFilter]->import($data, $defaultValues);
}
}
