Refs #4200, remove parameter from Truncate filter,and document AddSum…

…maryRow and Truncate filters.

core/DataTable.php

@@ -1103,7 +1103,6 @@ public function getSerialized($maximumRowsInDataTable = null,
                 array($maximumRowsInDataTable - 1,
                       DataTable::LABEL_SUMMARY_ROW,
                       $columnToSortByBeforeTruncation,
-                      $deleteRows = true,
                       $filterRecursive = false)
             );
         }

core/DataTable/Filter/AddSummaryRow.php

@@ -15,31 +15,26 @@
 use Piwik\DataTable\Row\DataTableSummaryRow;
 
 /**
- * Add a new row to the table containing a summary
- * of the rows from StartRowToSummarize to EndRowToSummarize.
- * It then deletes the rows from StartRowToSummarize to EndRowToSummarize.
- * The new row created has a label = 'other'
- *
- * This filter is useful to build a more compact view of a table,
- * keeping the first records unchanged.
- *
- * For example we use this for the pie chart, to build the last pie part
- * which is the sum of all the remaining data after the top 5 data.
- * This row is assigned a label of 'Others'.
+ * Add a summary row row to the table that is the sum of all other table
+ * rows.
  *
+ * **Basic usage example**
+ * 
+ *     $dataTable->filter('AddSummaryRow');
+ * 
+ *     // use a human readable label for the summary row (instead of '-1')
+ *     $dataTable->filter('AddSummaryRow', array($labelSummaryRow = Piwik_Translate('General_Total')));
+ * 
  * @package Piwik
  * @subpackage DataTable
  */
 class AddSummaryRow extends Filter
 {
     /**
-     * Creates a new filter and set all required parameters
+     * Constructor.
      *
-     * @param DataTable $table
-     * @param int $startRowToSummarize
-     * @param int $labelSummaryRow
-     * @param null $columnToSortByBeforeTruncating
-     * @param bool $deleteRows
+     * @param DataTable $table The table that will be filtered.
+     * @param int $labelSummaryRow The value of the label column for the new row.
      */
     public function __construct($table, $labelSummaryRow = DataTable::LABEL_SUMMARY_ROW)
     {
@@ -48,7 +43,7 @@ public function __construct($table, $labelSummaryRow = DataTable::LABEL_SUMMARY_
     }
 
     /**
-     * Adds a summary row to the given data table
+     * Executes the filter. See [AddSummaryRow](#).
      *
      * @param DataTable $table
      */

core/DataTable/Filter/Truncate.php

@@ -16,39 +16,61 @@
 use Piwik\DataTable\Row;
 
 /**
+ * Truncates a DataTable by merging all rows after a certain index into a new summary
+ * row.
+ * 
+ * The [ReplaceSummaryRow](#) filter will be queued after the table is truncated.
+ * 
+ * ### Examples
+ * 
+ * **Basic usage**
+ * 
+ *     $dataTable->filter('Truncate', array($truncateAfter = 500));
+ * 
+ * **Using a custom summary row label**
+ * 
+ *     $dataTable->filter('Truncate', array($truncateAfter = 500, $summaryRowLabel = Piwik::translate('General_Total')));
+ * 
  * @package Piwik
  * @subpackage DataTable
  */
 class Truncate extends Filter
 {
     /**
-     * @param DataTable $table
-     * @param int $truncateAfter
+     * Constructor.
+     * 
+     * @param DataTable $table The table that will be filtered eventually.
+     * @param int $truncateAfter The row index to truncate at. All rows passed this index will
+     *                           be removed.
+     * @param string $labelSummaryRow The label to use for the summary row. Defaults to
+     *                                `Piwik::translate('General_Others')`.
+     * @param string $columnToSortByBeforeTruncating The column to sort by before truncation, eg,
+     *                                               `'nb_visits'`.
+     * @param bool $filterRecursive If true executes this filter on all subtables descending from
+     *                              `$table`.
      */
     public function __construct($table,
                                 $truncateAfter,
-                                $labelSummaryRow = DataTable::LABEL_SUMMARY_ROW,
+                                $labelSummaryRow = null,
                                 $columnToSortByBeforeTruncating = null,
-                                $deleteRows = true,
                                 $filterRecursive = true)
     {
         parent::__construct($table);
         $this->truncateAfter = $truncateAfter;
         $this->labelSummaryRow = $labelSummaryRow;
         $this->columnToSortByBeforeTruncating = $columnToSortByBeforeTruncating;
-        $this->deleteRows = $deleteRows;
         $this->filterRecursive = $filterRecursive;
     }
 
     /**
-     * Truncates the table after X rows and adds a summary row
+     * Executes the filter, see [Truncate](#).
      *
      * @param DataTable $table
      */
     public function filter($table)
     {
         $this->addSummaryRow($table);
-        $table->queueFilter('ReplaceSummaryRowLabel');
+        $table->queueFilter('ReplaceSummaryRowLabel', array($this->labelSummaryRow));
 
         if ($this->filterRecursive) {
             foreach ($table->getRows() as $row) {
@@ -61,8 +83,7 @@ public function filter($table)
 
     public function addSummaryRow($table)
     {
-        $table->filter('Sort',
-            array($this->columnToSortByBeforeTruncating, 'desc'));
+        $table->filter('Sort', array($this->columnToSortByBeforeTruncating, 'desc'));
 
         if ($table->getRowsCount() <= $this->truncateAfter + 1) {
             return;
@@ -85,10 +106,7 @@ public function addSummaryRow($table)
             }
         }
 
-        $newRow->setColumns(array('label' => $this->labelSummaryRow) + $newRow->getColumns());
-        if ($this->deleteRows) {
-            $table->filter('Limit', array(0, $this->truncateAfter));
-        }
+        $table->filter('Limit', array(0, $this->truncateAfter));
         $table->addSummaryRow($newRow);
         unset($rows);
     }