/**
* Returns a DataTable_Array containing values
* of the element $name from the archives in this Archive_Array.
*
* The value to be returned are blob values (stored in the archive_numeric_* tables in the DB). *
* It can return anything from strings, to serialized PHP arrays or PHP objects, etc.
*
* @param string $name Name of the mysql table field to load eg. Referers_keywordBySearchEngine
*
* @return Piwik_DataTable_Array containing the requested blob values for each Archive
*/
public function getBlob($name)
{
$table = $this->getNewDataTableArray();
foreach ($this->archives as $archive) {
$blob = $archive->getBlob($name);
$subTable = new Piwik_DataTable_Simple();
$subTable->loadFromArray(array('blob' => $blob));
$table->addTable($subTable, $archive->getPrettyDate());
$this->loadMetaData($table, $archive);
}
return $table;
}
/**
* This method post processes the data resulting from the API call.
*
* - If the data resulted from the API call is a Piwik_DataTable then
* - we apply the standard filters if the parameters have been found
* in the URL. For example to offset,limit the Table you can add the following parameters to any API
* call that returns a DataTable: filter_limit=10&filter_offset=20
* - we apply the filters that have been previously queued on the DataTable
* @see Piwik_DataTable::queueFilter()
* - we apply the renderer that generate the DataTable in a given format (XML, PHP, HTML, JSON, etc.)
* the format can be changed using the 'format' parameter in the request.
* Example: format=xml
*
* - If there is nothing returned (void) we display a standard success message
*
* - If there is a PHP array returned, we try to convert it to a dataTable
* It is then possible to convert this datatable to any requested format (xml/etc)
*
* - If a bool is returned we convert to a string (true is displayed as 'true' false as 'false')
*
* - If an integer / float is returned, we simply return it
*
* @throws Exception If an object/resource is returned, if any of conversion fails, etc.
*
* @param mixed The initial returned value, before post process
* @return mixed Usually a string, but can still be a PHP data structure if the format requested is 'original'
*/
protected function handleReturnedValue($returnedValue)
{
$toReturn = $returnedValue;
// If the returned value is an object DataTable we
// apply the set of generic filters if asked in the URL
// and we render the DataTable according to the format specified in the URL
if ($returnedValue instanceof Piwik_DataTable || $returnedValue instanceof Piwik_DataTable_Array) {
if ($returnedValue instanceof Piwik_DataTable) {
$this->applyDataTableGenericFilters($returnedValue);
} elseif ($returnedValue instanceof Piwik_DataTable_Array) {
$tables = $returnedValue->getArray();
foreach ($tables as $table) {
$this->applyDataTableGenericFilters($table);
}
}
// if the flag disable_queued_filters is defined we skip the filters that were queued
// useful in some very rare cases but better to use this than a bad hack on the data returned...
if (Piwik_Common::getRequestVar('disable_queued_filters', 'false', 'string', $this->requestToUse) == 'false') {
$returnedValue->applyQueuedFilters();
}
$toReturn = $this->getRenderedDataTable($returnedValue);
} elseif (!isset($toReturn)) {
$toReturn = $this->getStandardSuccessOutput($this->outputFormatRequested);
} elseif (is_array($toReturn)) {
if ($this->outputFormatRequested == 'original') {
// we handle the serialization. Because some php array have a very special structure that
// couldn't be converted with the automatic DataTable->loadFromSimpleArray
// the user may want to request the original PHP data structure serialized by the API
// in case he has to setup serialize=1 in the URL
if ($this->caseRendererPHPSerialize($defaultSerialize = 0)) {
$toReturn = serialize($toReturn);
}
} else {
$dataTable = new Piwik_DataTable();
$dataTable->loadFromSimpleArray($toReturn);
$toReturn = $this->getRenderedDataTable($dataTable);
}
} else {
// original data structure requested, we return without process
if ($this->outputFormatRequested == 'original') {
return $toReturn;
}
if ($toReturn === true) {
$toReturn = 'true';
} elseif ($toReturn === false) {
$toReturn = 'false';
} elseif (is_object($toReturn) || is_resource($toReturn)) {
return $this->getExceptionOutput(' The API cannot handle this data structure. You can get the data internally by directly using the class.', $this->outputFormatRequested);
}
require_once "DataTable/Simple.php";
$dataTable = new Piwik_DataTable_Simple();
$dataTable->loadFromArray(array($toReturn));
$toReturn = $this->getRenderedDataTable($dataTable);
}
return $toReturn;
}
/**
* Returns a DataTable_Simple with one row per field from $fields array names.
*
* @param string|array $fields Name or array of names of Archive fields
*
* @return Piwik_DataTable_Simple
*/
public function getDataTableFromNumeric($fields)
{
require_once "DataTable/Simple.php";
if (!is_array($fields)) {
$fields = array($fields);
}
$values = array();
foreach ($fields as $field) {
$values[$field] = $this->getNumeric($field);
}
$table = new Piwik_DataTable_Simple();
$table->loadFromArray($values);
return $table;
}
