### Examples
**Creating a ViewDataTable for a report**
method in MyPlugin\Controller
public function myReport()
{
$view = Factory::build('table', 'MyPlugin.myReport');
$view->config->show_limit_control = true;
$view->config->translations['myFancyMetric'] = "My Fancy Metric";
return $view->render();
}
**Displaying a report in another way**
method in MyPlugin\Controller
use the same data that's used in myReport() above, but transform it in some way before
displaying.
public function myReportShownDifferently()
{
$view = Factory::build('table', 'MyPlugin.myReport', 'MyPlugin.myReportShownDifferently');
$view->config->filters[] = array('MyMagicFilter', array('an arg', 'another arg'));
return $view->render();
}
**Force a report to be shown as a bar graph**
method in MyPlugin\Controller
force the myReport report to show as a bar graph if there is no viewDataTable query param,
even though it is configured to show as a table.
public function myReportShownAsABarGraph()
{
$view = Factory::build('graphVerticalBar', 'MyPlugin.myReport', 'MyPlugin.myReportShownAsABarGraph',
$forceDefault = true);
return $view->render();
}
/**
* Generates a graphic report based on the given parameters
* @param string $type
* @param string $apiMethod
* @param string $controllerMethod
* @param array $selectable
* @param array $to_display
* @return View
*/
private function getReportGraph($type, $apiMethod, $controllerMethod, $selectable = array(), $to_display = array())
{
$view = ViewDataTableFactory::build($type, $apiMethod, $controllerMethod, $forceDefault = true);
$view->config->show_goals = false;
if (empty($selectable)) {
if (Common::getRequestVar('period', false) == 'day') {
$selectable = array('nb_visits', 'nb_uniq_visitors', 'nb_actions');
} else {
$selectable = array('nb_visits', 'nb_actions');
}
}
if (empty($to_display)) {
$to_display = Common::getRequestVar('columns', false);
if (false !== $to_display) {
$to_display = Piwik::getArrayFromApiParameter($columns);
}
}
if (false !== $to_display) {
$to_display = !is_array($to_display) ? array($to_display) : $to_display;
} else {
$to_display = $selectable;
}
$view->config->selectable_columns = $selectable;
$view->config->columns_to_display = $to_display;
$view->config->show_footer_icons = false;
return $this->renderView($view);
}
/**
* Returns a ViewDataTable object that will render a jqPlot evolution graph
* for the last30 days/weeks/etc. of the current period, relative to the current date.
*
* @param string $currentModuleName The name of the current plugin.
* @param string $currentControllerAction The name of the action that renders the desired
* report.
* @param string $apiMethod The API method that the ViewDataTable will use to get
* graph data.
* @return ViewDataTable
* @api
*/
protected function getLastUnitGraph($currentModuleName, $currentControllerAction, $apiMethod)
{
$view = ViewDataTableFactory::build(Evolution::ID, $apiMethod, $currentModuleName . '.' . $currentControllerAction, $forceDefault = true);
$view->config->show_goals = false;
return $view;
}
/**
* Renders a report depending on the configured ViewDataTable see {@link configureView()} and
* {@link getDefaultTypeViewDataTable()}. If you want to customize the render process or just render any custom view
* you can overwrite this method.
*
* @return string
* @throws \Exception In case the given API action does not exist yet.
* @api
*/
public function render()
{
$apiProxy = Proxy::getInstance();
if (!$apiProxy->isExistingApiAction($this->module, $this->action)) {
throw new Exception("Invalid action name '{$this->action}' for '{$this->module}' plugin.");
}
$apiAction = $apiProxy->buildApiActionName($this->module, $this->action);
$view = ViewDataTableFactory::build(null, $apiAction, $this->module . '.' . $this->action);
$rendered = $view->render();
return $rendered;
}
public function treemap()
{
$view = ViewDataTableFactory::build('infoviz-treemap', 'ExampleUI.getTemperatures', $controllerAction = 'ExampleUI.treemap');
$view->config->translations['value'] = "Temperature";
$view->config->columns_to_display = array("label", "value");
$view->config->selectable_columns = array("value");
$view->config->show_evolution_values = 0;
return $view->render();
}
public function getSparklines()
{
$metrics = $this->getReferrersVisitorsByType();
$distinctMetrics = $this->getDistinctReferrersMetrics();
$numberFormatter = NumberFormatter::getInstance();
$totalVisits = array_sum($metrics);
foreach ($metrics as $name => $value) {
// calculate percent of total, if there were any visits
if ($value != 0 && $totalVisits != 0) {
$percentName = $name . 'Percent';
$metrics[$percentName] = round($value / $totalVisits * 100, 0);
}
}
// calculate evolution for visit metrics & distinct metrics
list($lastPeriodDate, $ignore) = Range::getLastDate();
if ($lastPeriodDate !== false) {
$date = Common::getRequestVar('date');
$period = Common::getRequestVar('period');
$prettyDate = self::getPrettyDate($date, $period);
$prettyLastPeriodDate = self::getPrettyDate($lastPeriodDate, $period);
// visit metrics
$previousValues = $this->getReferrersVisitorsByType($lastPeriodDate);
$metrics = $this->addEvolutionPropertiesToView($prettyDate, $metrics, $prettyLastPeriodDate, $previousValues);
// distinct metrics
$previousValues = $this->getDistinctReferrersMetrics($lastPeriodDate);
$distinctMetrics = $this->addEvolutionPropertiesToView($prettyDate, $distinctMetrics, $prettyLastPeriodDate, $previousValues);
}
/** @var Sparklines $view */
$view = ViewDataTable\Factory::build(Sparklines::ID, $api = '', $controller = '', $force = true, $loadUserParams = false);
// DIRECT ENTRY
$metrics['visitorsFromDirectEntry'] = $numberFormatter->formatNumber($metrics['visitorsFromDirectEntry']);
$values = array($metrics['visitorsFromDirectEntry']);
$descriptions = array(Piwik::translate('Referrers_TypeDirectEntries'));
if (!empty($metrics['visitorsFromDirectEntryPercent'])) {
$metrics['visitorsFromDirectEntryPercent'] = $numberFormatter->formatPercent($metrics['visitorsFromDirectEntryPercent'], $precision = 1);
$values[] = $metrics['visitorsFromDirectEntryPercent'];
$descriptions[] = Piwik::translate('Referrers_XPercentOfVisits');
}
$directEntryParams = $this->getReferrerSparklineParams(Common::REFERRER_TYPE_DIRECT_ENTRY);
$view->config->addSparkline($directEntryParams, $values, $descriptions, @$metrics['visitorsFromDirectEntryEvolution']);
// WEBSITES
$metrics['visitorsFromWebsites'] = $numberFormatter->formatNumber($metrics['visitorsFromWebsites']);
$values = array($metrics['visitorsFromWebsites']);
$descriptions = array(Piwik::translate('Referrers_TypeWebsites'));
if (!empty($metrics['visitorsFromWebsitesPercent'])) {
$metrics['visitorsFromWebsitesPercent'] = $numberFormatter->formatPercent($metrics['visitorsFromWebsitesPercent'], $precision = 1);
$values[] = $metrics['visitorsFromWebsitesPercent'];
$descriptions[] = Piwik::translate('Referrers_XPercentOfVisits');
}
$searchEngineParams = $this->getReferrerSparklineParams(Common::REFERRER_TYPE_WEBSITE);
$view->config->addSparkline($searchEngineParams, $values, $descriptions, @$metrics['visitorsFromWebsitesEvolution']);
// SEARCH ENGINES
$metrics['visitorsFromSearchEngines'] = $numberFormatter->formatNumber($metrics['visitorsFromSearchEngines']);
$values = array($metrics['visitorsFromSearchEngines']);
$descriptions = array(Piwik::translate('Referrers_TypeSearchEngines'));
if (!empty($metrics['visitorsFromSearchEnginesPercent'])) {
$metrics['visitorsFromSearchEnginesPercent'] = $numberFormatter->formatPercent($metrics['visitorsFromSearchEnginesPercent'], $precision = 1);
$values[] = $metrics['visitorsFromSearchEnginesPercent'];
$descriptions[] = Piwik::translate('Referrers_XPercentOfVisits');
}
$searchEngineParams = $this->getReferrerSparklineParams(Common::REFERRER_TYPE_SEARCH_ENGINE);
$view->config->addSparkline($searchEngineParams, $values, $descriptions, @$metrics['visitorsFromSearchEnginesEvolution']);
// CAMPAIGNS
$metrics['visitorsFromCampaigns'] = $numberFormatter->formatNumber($metrics['visitorsFromCampaigns']);
$values = array($metrics['visitorsFromCampaigns']);
$descriptions = array(Piwik::translate('Referrers_TypeCampaigns'));
if (!empty($metrics['visitorsFromCampaignsPercent'])) {
$metrics['visitorsFromCampaignsPercent'] = $numberFormatter->formatPercent($metrics['visitorsFromCampaignsPercent'], $precision = 1);
$values[] = $metrics['visitorsFromCampaignsPercent'];
$descriptions[] = Piwik::translate('Referrers_XPercentOfVisits');
}
$searchEngineParams = $this->getReferrerSparklineParams(Common::REFERRER_TYPE_CAMPAIGN);
$view->config->addSparkline($searchEngineParams, $values, $descriptions, @$metrics['visitorsFromCampaignsEvolution']);
// DISTINCT SEARCH ENGINES
$sparklineParams = $this->getDistinctSparklineUrlParams('getLastDistinctSearchEnginesGraph');
$value = $distinctMetrics['numberDistinctSearchEngines'];
$value = $numberFormatter->formatNumber($value);
$description = Piwik::translate('Referrers_DistinctSearchEngines');
$view->config->addSparkline($sparklineParams, $value, $description, @$distinctMetrics['numberDistinctSearchEnginesEvolution']);
// DISTINCT WEBSITES
$sparklineParams = $this->getDistinctSparklineUrlParams('getLastDistinctWebsitesGraph');
$distinctMetrics['numberDistinctWebsites'] = $numberFormatter->formatNumber($distinctMetrics['numberDistinctWebsites']);
$distinctMetrics['numberDistinctWebsitesUrls'] = $numberFormatter->formatNumber($distinctMetrics['numberDistinctWebsitesUrls']);
$values = array($distinctMetrics['numberDistinctWebsites'], $distinctMetrics['numberDistinctWebsitesUrls']);
$descriptions = array(Piwik::translate('Referrers_DistinctWebsites'), Piwik::translate('Referrers_UsingNDistinctUrls'));
$view->config->addSparkline($sparklineParams, $values, $descriptions, @$distinctMetrics['numberDistinctWebsitesEvolution']);
// DISTINCT KEYWORDS
$sparklineParams = $this->getDistinctSparklineUrlParams('getLastDistinctKeywordsGraph');
$value = $distinctMetrics['numberDistinctKeywords'];
$value = $numberFormatter->formatNumber($value);
$description = Piwik::translate('Referrers_DistinctKeywords');
$view->config->addSparkline($sparklineParams, $value, $description, @$distinctMetrics['numberDistinctKeywordsEvolution']);
// DISTINCT CAMPAIGNS
$sparklineParams = $this->getDistinctSparklineUrlParams('getLastDistinctCampaignsGraph');
$value = $distinctMetrics['numberDistinctCampaigns'];
$value = $numberFormatter->formatNumber($value);
$description = Piwik::translate('Referrers_DistinctCampaigns');
$view->config->addSparkline($sparklineParams, $value, $description, @$distinctMetrics['numberDistinctCampaignsEvolution']);
return $view->render();
}
/**
* Generic method to get an evolution graph or a sparkline for the row evolution popover.
* Do as much as possible from outside the controller.
* @param string|bool $graphType
* @param array|bool $metrics
* @return Factory
*/
public function getRowEvolutionGraph($graphType = false, $metrics = false)
{
// set up the view data table
$view = Factory::build($graphType ?: $this->graphType, $this->apiMethod, $controllerAction = 'CoreHome.getRowEvolutionGraph', $forceDefault = true);
$view->setDataTable($this->dataTable);
if (!empty($this->graphMetrics)) {
// In row Evolution popover, this is empty
$view->config->columns_to_display = array_keys($metrics ?: $this->graphMetrics);
}
$view->requestConfig->request_parameters_to_modify['label'] = '';
$view->config->show_goals = false;
$view->config->show_search = false;
$view->config->show_all_views_icons = false;
$view->config->show_active_view_icon = false;
$view->config->show_related_reports = false;
$view->config->show_series_picker = false;
$view->config->show_footer_message = false;
foreach ($this->availableMetrics as $metric => $metadata) {
$view->config->translations[$metric] = $metadata['name'];
}
$view->config->external_series_toggle = 'RowEvolutionSeriesToggle';
$view->config->external_series_toggle_show_all = $this->initiallyShowAllMetrics;
return $view;
}
/**
* @param $controllerAction
* @param $params
* @return ViewDataTable
* @throws \Exception
*/
private static function makeTemporaryViewDataTableInstance($controllerAction, $params)
{
$report = new Report();
$viewDataTableType = isset($params['viewDataTable']) ? $params['viewDataTable'] : $report->getDefaultTypeViewDataTable();
$apiAction = $controllerAction;
$loadViewDataTableParametersForUser = false;
$viewDataTable = Factory::build($viewDataTableType, $apiAction, $controllerAction, $forceDefault = false, $loadViewDataTableParametersForUser);
return $viewDataTable;
}
/**
* Renders a report depending on the configured ViewDataTable see {@link configureView()} and
* {@link getDefaultTypeViewDataTable()}. If you want to customize the render process or just render any custom view
* you can overwrite this method.
*
* @return string
* @throws \Exception In case the given API action does not exist yet.
* @api
*/
public function render()
{
$viewDataTable = Common::getRequestVar('viewDataTable', false, 'string');
$fixed = Common::getRequestVar('forceView', 0, 'int');
$module = $this->getModule();
$action = $this->getAction();
$apiProxy = Proxy::getInstance();
if (!$apiProxy->isExistingApiAction($module, $action)) {
throw new Exception("Invalid action name '{$module}' for '{$action}' plugin.");
}
$apiAction = $apiProxy->buildApiActionName($module, $action);
$view = ViewDataTableFactory::build($viewDataTable, $apiAction, $module . '.' . $action, $fixed);
return $view->render();
}