Refs #4040, #4041, added ability to access view properties directly, …

…started documenting view properties and modified ExampleUI plugin to set view properties directly.

core/ViewDataTable.php

@@ -36,6 +36,7 @@
  *    }
  * </pre>
  *
+ * @see Piwik_ViewDataTable_Properties for core DataTable display properties.
  * @see factory() for all the available output (cloud tags, html table, pie chart, vertical bar chart)
  * @package Piwik
  * @subpackage Piwik_ViewDataTable
@@ -112,7 +113,6 @@ abstract class Piwik_ViewDataTable
      */
     protected $view = null;
 
-
     /**
      * Default constructor.
      */
@@ -173,6 +173,37 @@ public function __construct()
         }
     }
 
+    /**
+     * Gets a view property by reference.
+     * 
+     * @param string $name A valid view property name. @see Piwik_ViewDataTable_Properties for all
+     *                     valid view properties.
+     * @return mixed
+     * @throws Exception if the property name is invalid.
+     */
+    public function &__get($name)
+    {
+        Piwik_ViewDataTable_Properties::checkValidPropertyName($name);
+
+        return $this->viewProperties[$name];
+    }
+
+    /**
+     * Sets a view property.
+     * 
+     * @param string $name A valid view property name. @see Piwik_ViewDataTable_Properties for all
+     *                     valid view properties.
+     * @param mixed $value
+     * @return mixed Returns $value.
+     * @throws Exception if the property name is invalid.
+     */
+    public function __set($name, $value)
+    {
+        Piwik_ViewDataTable_Properties::checkValidPropertyName($name);
+
+        return $this->viewProperties[$name] = $value;
+    }
+
     /**
      * Method to be implemented by the ViewDataTable_*.
      * This method should create and initialize a $this->view object @see Piwik_View_Interface
@@ -196,16 +227,21 @@ abstract protected function getViewDataTableId();
      * If force is set to true, a ViewDataTable of the $defaultType will be returned in all cases.
      *
      * @param string $defaultType Any of these: table, cloud, graphPie, graphVerticalBar, graphEvolution, sparkline, generateDataChart*
-     * @param string|bool $action
+     * @param string|bool $apiAction
+     * @param string|bool $controllerAction
      * @return Piwik_ViewDataTable
      */
-    static public function factory($defaultType = null, $action = false)
+    static public function factory($defaultType = null, $apiAction = false, $controllerAction = false)
     {
-        if ($action !== false) {
-            $defaultProperties = self::getDefaultPropertiesForReport($action);
+        if ($apiAction !== false) {
+            $defaultProperties = self::getDefaultPropertiesForReport($apiAction);
             if (isset($defaultProperties['default_view_type'])) {
                 $defaultType = $defaultProperties['default_view_type'];
             }
+
+            if ($controllerAction === false) {
+                $controllerAction = $apiAction;
+            }
         }
 
         if ($defaultType === null) {
@@ -248,15 +284,15 @@ static public function factory($defaultType = null, $action = false)
                 break;
         }
 
-        if ($action !== false) {
-            list($plugin, $controllerAction) = explode('.', $action);
+        if ($apiAction !== false) {
+            list($plugin, $controllerAction) = explode('.', $controllerAction);
 
             $subtableAction = $controllerAction;
             if (isset($defaultProperties['subtable_action'])) {
                 $subtableAction = $defaultProperties['subtable_action'];
             }
 
-            $result->init($plugin, $controllerAction, $action, $subtableAction, $defaultProperties);
+            $result->init($plugin, $controllerAction, $apiAction, $subtableAction, $defaultProperties);
         }
 
         return $result;
@@ -1583,23 +1619,33 @@ private function getBaseReportUrl($module, $action, $queryParams = array())
      * @param bool $fetch If true, the result is returned, if false it is echo'd.
      * @return string|null See $fetch.
      */
-    static public function render($pluginName, $apiAction, $fetch = true)
+    static public function renderReport($pluginName, $apiAction, $fetch = true)
     {
         $apiClassName = 'Piwik_'.$pluginName.'_API';
         if (!method_exists($apiClassName::getInstance(), $apiAction)) {
             throw new Exception("Invalid action name '$apiAction' for '$pluginName' plugin.");
         }
 
         $view = self::factory(null, $pluginName.'.'.$apiAction);
-        $view->main();
-        $rendered = $view->getView()->render();
+        $rendered = $view->render();
 
         if ($fetch) {
             return $rendered;
         } else {
             echo $rendered;
         }
     }
+
+    /**
+     * Convenience function. Calls main() & renders the view that gets built.
+     * 
+     * @return string The result of rendering.
+     */
+    public function render()
+    {
+        $this->main();
+        return $this->getView()->render();
+    }
 
     /**
      * Returns whether the DataTable result will have to be expanded for the
@@ -1624,7 +1670,7 @@ public static function shouldLoadExpanded()
      * @param array|string $columnsToCheckFor eg, array('nb_visits', 'nb_uniq_visitors')
      * @return bool
      */
-    private function dataTableColumnsContains($columns, $columnsToCheckFor)
+    protected function dataTableColumnsContains($columns, $columnsToCheckFor)
     {
         if (!is_array($columnsToCheckFor)) {
             $columnsToCheckFor = array($columnsToCheckFor);
@@ -1659,7 +1705,7 @@ protected function buildView($visualization, $template = false)
 
         $view->visualization = $visualization;
 
-        if (!$this->isDataAvailable) {
+        if (!$this->dataTable === null) {
             $view->dataTable = null;
         } else {
             $view->dataTable = $this->dataTable;

core/ViewDataTable/Cloud.php

@@ -49,11 +49,12 @@ public function main()
         }
         $this->mainAlreadyExecuted = true;
 
-        $this->isDataAvailable = true;
         try {
             $this->loadDataTableFromAPI();
         } catch (Exception $e) {
-            $this->isDataAvailable = false;
+            Piwik::log("Failed to get data from API: " . $e->getMessage());
+
+            $this->loadingError = array('message' => $e->getMessage());
         }
 
         $this->checkStandardDataTable();

core/ViewDataTable/GenerateGraphHTML.php

@@ -221,15 +221,13 @@ public function main()
         // will be done on the table before the labels are enhanced (see ReplaceColumnNames)
         $this->disableQueuedFilters();
 
-        $this->isDataAvailable = true;
         try {
             $this->loadDataTableFromAPI();
         } catch (Piwik_Access_NoAccessException $e) {
             throw $e;
         } catch (Exception $e) {
             Piwik::log("Failed to get data from API: " . $e->getMessage());
 
-            $this->isDataAvailable = false;
             $this->loadingError = array('message' => $e->getMessage());
         }
 

core/ViewDataTable/HtmlTable.php

@@ -64,15 +64,13 @@ public function main()
         }
         $this->mainAlreadyExecuted = true;
 
-        $this->isDataAvailable = true;
         try {
             $this->loadDataTableFromAPI();
         } catch (Piwik_Access_NoAccessException $e) {
             throw $e;
         } catch (Exception $e) {
             Piwik::log("Failed to get data from API: " . $e->getMessage());
 
-            $this->isDataAvailable = false;
             $this->loadingError = array('message' => $e->getMessage());
         }
 

core/ViewDataTable/HtmlTable/AllColumns.php

@@ -38,9 +38,8 @@ protected function postDataTableLoadedFromAPI()
         $valid = parent::postDataTableLoadedFromAPI();
         if (!$valid) return false;
 
-        Piwik_Controller::setPeriodVariablesView($this);
         $columnUniqueVisitors = false;
-        if ($this->period == 'day') {
+        if ($this->dataTableColumnsContains($this->dataTable->getColumns(), 'nb_uniq_visitors')) {
             $columnUniqueVisitors = 'nb_uniq_visitors';
         }
 

core/ViewDataTable/HtmlTable/Goals.php

@@ -15,6 +15,9 @@
  */
 class Piwik_ViewDataTable_HtmlTable_Goals extends Piwik_ViewDataTable_HtmlTable
 {
+    private $processOnlyIdGoal = null;
+    private $isEcommerce = false;
+
     protected function getViewDataTableId()
     {
         return 'tableGoals';

core/ViewDataTable/Properties.php

@@ -0,0 +1,141 @@
+<?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
+ */
+
+/**
+ * Contains the list of all core DataTable display properties for use with ViewDataTable.
+ * 
+ * @see Piwik_ViewDataTable for more info.
+ * 
+ * TODO: change the names of properties to match the const names where appropriate.
+ */
+class Piwik_ViewDataTable_Properties
+{
+    /**
+     * This property determines which Twig template to use when rendering a ViewDataTable.
+     * 
+     * TODO: shouldn't have this property. should only use visualization classes.
+     */
+    const DATATABLE_TEMPLATE = 'datatable_template';
+
+    /**
+     * Controls whether the goals footer icon is shown.
+     */
+    const SHOW_GOALS = 'show_goals';
+
+    /**
+     * Array property mapping DataTable column names with their internationalized names.
+     */
+    const COLUMN_NAME_TRANSLATIONS = 'translations';
+
+    /**
+     * Controls which column to sort the DataTable by before truncating and displaying.
+     */
+    const SORTED_COLUMN = 'filter_sort_column';
+
+    /**
+     * Controls the sort order. Either 'asc' or 'desc'.
+     * 
+     * @see self::SORTED_COLUMN
+     */
+    const SORT_ORDER = 'filter_sort_order';
+
+    /**
+     * The limit used when rendering a jqPlot graph.
+     * 
+     * TODO: either replace w/ filter_limit, or make it a visualization property.
+     */
+    const GRAPH_LIMIT = 'graph_limit';
+
+    /**
+     * The number of items to truncate the data set to before rendering the DataTable view.
+     */
+    const LIMIT = 'filter_limit';
+
+    /**
+     * Controls whether the 'Exclude Low Population' option (visible in the popup that displays after
+     * clicking the 'cog' icon) is shown.
+     */
+    const SHOW_EXCLUDE_LOW_POPULATION = 'show_exclude_low_population';
+
+    /**
+     * Controls whether the 'All Columns' footer icon is shown.
+     */
+    const SHOW_ALL_TABLES_VIEW = 'show_table_all_columns';
+
+    /**
+     * Controls whether the Row Evolution datatable row action icon is shown.
+     */
+    const DISABLE_ROW_EVOLUTION = 'disable_row_evolution';
+
+    /**
+     * The unit to display in jqPlot graphs.
+     * 
+     * TODO: Either this should be a visualization property, or should be named something different.
+     */
+    const Y_AXIS_UNIT = 'y_axis_unit';
+
+    /**
+     * Controls whether the entire view footer is shown.
+     */
+    const SHOW_FOOTER = 'show_footer';
+
+    /**
+     * Controls whether the row that contains all footer icons & the limit selector is shown.
+     */
+    const SHOW_FOOTER_ICONS = 'show_footer_icons';
+
+    /**
+     * Array property that determines which columns will be shown. Columns not in this array
+     * should not appear in ViewDataTable visualizations.
+     * 
+     * Example: array('label', 'nb_visits', 'nb_uniq_visitors')
+     */
+    const COLUMNS_TO_DISPLAY = 'columns_to_display';
+
+    /**
+     * Whether to display the logo assocatied with a DataTable row (stored as 'logo' row metadata)
+     * isntead of the label in Tag Clouds.
+     */
+    const DISPLAY_LOGO_INSTEAD_OF_LABEL = 'display_logo_instead_of_label';
+
+    /**
+     * Returns the set of all valid ViewDataTable properties. The result is an array with property
+     * name as a key. Values of the array are undefined.
+     * 
+     * @return array
+     */
+    public static function getAllProperties()
+    {
+        static $propertiesCache = null;
+
+        if ($propertiesCache === null) {
+            $klass = new ReflectionClass(__CLASS__);
+            $propertiesCache = array_flip($klass->getConstants());
+        }
+
+        return $propertiesCache;
+    }
+
+    /**
+     * Checks if a property is a valid ViewDataTable property, and if not, throws an exception.
+     *
+     * @param string $name The property name.
+     * @throws Exception
+     */
+    public static function checkValidPropertyName($name)
+    {
+        $properties = self::getAllProperties();
+        if (!isset($properties[$name])) {
+            throw new Exception("Invalid ViewDataTable display property '$name'. Is this a visualization property? "
+                              . "If so, set it with \$view->visualization_properties->$name = ...");
+        }
+    }
+}

core/ViewDataTable/Sparkline.php

@@ -43,10 +43,8 @@ public function main()
         $_GET['period'] = $period;
 
         $values = $this->getValuesFromDataTable($this->dataTable);
-        $this->isDataAvailable = true;
         if (empty($values)) {
             $values = array_fill(0, 30, 0);
-            $this->isDataAvailable = false;
         }
 
         $graph = new Piwik_Visualization_Sparkline();