ViewDataTable.php

<?php
/**
 * Piwik - Open source web analytics
 *
 * @link http://piwik.org
 * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
 *
 * @category Piwik
 * @package Piwik
 */

/**
 * This class is used to load (from the API) and customize the output of a given DataTable.
 * The main() method will create an object implementing Piwik_View_Interface
 * You can customize the dataTable using the disable* methods.
 *
 * You can also customize the dataTable rendering using row metadata:
 * - 'html_label_prefix': If this metadata is present on a row, it's contents will be prepended
 *                        the label in the HTML output.
 * - 'html_label_suffix': If this metadata is present on a row, it's contents will be appended
 *                        after the label in the HTML output.
 *
 * Example:
 * In the Controller of the plugin VisitorInterest
 * <pre>
 *    function getNumberOfVisitsPerVisitDuration( $fetch = false)
 *  {
 *        $view = Piwik_ViewDataTable::factory( 'cloud' );
 *        $view->init( $this->pluginName,  __FUNCTION__, 'VisitorInterest.getNumberOfVisitsPerVisitDuration' );
 *        $view->setColumnsToDisplay( array('label','nb_visits') );
 *        $view->disableSort();
 *        $view->disableExcludeLowPopulation();
 *        $view->disableOffsetInformation();
 *
 *        return $this->renderView($view, $fetch);
 *    }
 * </pre>
 *
 * @see factory() for all the available output (cloud tags, html table, pie chart, vertical bar chart)
 * @package Piwik
 * @subpackage Piwik_ViewDataTable
 */
abstract class Piwik_ViewDataTable
{
    /**
     * Cache for getAllReportDisplayProperties result.
     * 
     * @var array
     */
    public static $reportPropertiesCache = null;

    /**
     * Template file that will be loaded for this view.
     * Usually set in the Piwik_ViewDataTable_*
     *
     * @var string eg. 'CoreHome/templates/cloud.twig'
     */
    protected $dataTableTemplate = null;

    /**
     * Flag used to make sure the main() is only executed once
     *
     * @var bool
     */
    protected $mainAlreadyExecuted = false;

    /**
     * Array of properties that are available in the view
     * Used to store UI properties, eg. "show_footer", "show_search", etc.
     *
     * @var array
     */
    protected $viewProperties = array();
    
    /**
     * If the current dataTable refers to a subDataTable (eg. keywordsBySearchEngineId for id=X) this variable is set to the Id
     *
     * @var bool|int
     */
    protected $idSubtable = false;

    /**
     * DataTable loaded from the API for this ViewDataTable.
     *
     * @var Piwik_DataTable
     */
    protected $dataTable = null;

    /**
     * List of filters to apply after the data has been loaded from the API
     *
     * @var array
     */
    protected $queuedFilters = array();

    /**
     * List of filter to apply just before the 'Generic' filters
     * These filters should delete rows from the table
     * @var array
     */
    protected $queuedFiltersPriority = array();

    /**
     * @see init()
     * @var string
     */
    protected $currentControllerAction;

    /**
     * @see init()
     * @var string
     */
    protected $currentControllerName;

    /**
     * This view should be an implementation of the Interface Piwik_View_Interface
     * The $view object should be created in the main() method.
     *
     * @var Piwik_View_Interface
     */
    protected $view = null;

    
    /**
     * Default constructor.
     */
    public function __construct()
    {
        $this->viewProperties['show_goals'] = false;
        $this->viewProperties['show_ecommerce'] = false;
        $this->viewProperties['show_search'] = true;
        $this->viewProperties['show_table'] = true;
        $this->viewProperties['show_table_all_columns'] = true;
        $this->viewProperties['show_all_views_icons'] = true;
        $this->viewProperties['hide_all_views_icons'] = false;
        $this->viewProperties['hide_annotations_view'] = true;
        $this->viewProperties['show_bar_chart'] = true;
        $this->viewProperties['show_pie_chart'] = true;
        $this->viewProperties['show_tag_cloud'] = true;
        $this->viewProperties['show_export_as_image_icon'] = false;
        $this->viewProperties['show_export_as_rss_feed'] = true;
        $this->viewProperties['show_exclude_low_population'] = true;
        $this->viewProperties['show_offset_information'] = true;
        $this->viewProperties['show_pagination_control'] = true;
        $this->viewProperties['show_limit_control'] = false;
        $this->viewProperties['show_footer'] = true;
        $this->viewProperties['show_related_reports'] = true;
        $this->viewProperties['exportLimit'] = Piwik_Config::getInstance()->General['API_datatable_default_limit'];
        $this->viewProperties['highlight_summary_row'] = false;
        $this->viewProperties['metadata'] = array();
        $this->viewProperties['relatedReports'] = array();
        $this->viewProperties['title'] = 'unknown';
        $this->viewProperties['tooltip_metadata_name'] = false;
        $this->viewProperties['enable_sort'] = true;
        $this->viewProperties['disable_generic_filters'] = false;
        $this->viewProperties['disable_queued_filters'] = false;
        $this->viewProperties['keep_summary_row'] = false;
        $this->viewProperties['filter_excludelowpop'] = false;
        $this->viewProperties['filter_excludelowpop_value'] = false;
        $this->viewProperties['filter_pattern'] = false;
        $this->viewProperties['filter_column'] = false;
        $this->viewProperties['filter_limit'] = false;
        $this->viewProperties['filter_sort_column'] = false;
        $this->viewProperties['filter_sort_order'] = false;
        $this->viewProperties['custom_parameters'] = array();
        $this->viewProperties['translations'] = array_merge(
            Piwik_Metrics::getDefaultMetrics(),
            Piwik_Metrics::getDefaultProcessedMetrics()
        );
        $this->viewProperties['request_parameters_to_modify'] = array();
        $this->viewProperties['documentation'] = false;
        $this->viewProperties['subtable_controller_action'] = false;
        $this->viewProperties['datatable_css_class'] = $this->getDefaultDataTableCssClass();
        $this->viewProperties['columns_to_display'] = array();

        $columns = Piwik_Common::getRequestVar('columns', false);
        if ($columns !== false) {
            $this->viewProperties['columns_to_display'] = Piwik::getArrayFromApiParameter($columns);
            array_unshift($this->viewProperties['columns_to_display'], 'label');
        }
    }

    /**
     * Method to be implemented by the ViewDataTable_*.
     * This method should create and initialize a $this->view object @see Piwik_View_Interface
     *
     * @return mixed either prints the result or returns the output string
     */
    abstract public function main();

    /**
     * Unique string ID that defines the format of the dataTable, eg. "pieChart", "table", etc.
     *
     * @return string
     */
    abstract protected function getViewDataTableId();

    /**
     * Returns a Piwik_ViewDataTable_* object.
     * By default it will return a ViewDataTable_Html