making totals more usable, extended doc, work in progress

Author: mvorisek

demos/collection/table.php

@@ -35,11 +35,17 @@
     'name'   => 'Total {$_row_count} rows:',
     'surname'=> [
         // longest surname
-        function ($total, $value, $model) {
+        'compare'=> function ($total, $value, $model) {
             return strlen($value) > strlen($total) ? $value : $total;
         },
+        'title'=> function ($total, $model) {
+            return 'Shortes is: '.$total;
+        },
+    ],
+    'salary' => [
+        'init'  => '123',
+        'update'=> null,
     ],
-    'salary' => ['sum'],
 ]);
 
 // 2nd table
@@ -51,8 +57,15 @@ function ($total, $value, $model) {
 ];
 
 $table = $app->add('Table');
+
 $table->setSource($my_array, ['name']);
 
+$table->addColumn('no');
+
+$table->addHook('beforeRow', function ($t) {
+    $t->model['no'] = @++$t->npk;
+});
+
 //$table->addColumn('name');
 $table->addColumn('surname', ['Link', 'url' => 'details.php?surname={$surname}']);
 $table->addColumn('birthdate', null, ['type' => 'date']);

docs/table.rst

@@ -88,52 +88,8 @@ You can also add individual column to your table::
 When invoking addColumn, you have a great control over the field properties and decoration. The format
 of addColumn() is very similar to :php:meth:`Form::addField`.
 
-Calculations
-============
-
-Apart from adding columns that reflect currrent values of your database, there are several ways
-how you can calculate additional values. You must know the capabilities of your database server
-if you want to execute some calculation there. (See http://agile-data.readthedocs.io/en/develop/expressions.html)
-
-It's always a good idea to calculate column inside datababase. Lets create "total" column  which will
-multiply "price" and "amount" values. Use ``addExpression`` to provide in-line definition for this
-field if it's not alrady defined in ``Order::init()``::
-
-    $table = $app->add('Table');
-    $order = new Order($db);
-
-    $order->addExpression('total', '[price]*[amount]')->type = 'money';
-
-    $table->setModel($order, ['name', 'price', 'amount', 'total', 'status']);
-
-The type of the Model Field determines the way how value is presented in the table. I've specified
-value to be 'money' which makes column align values to the right, format it with 2 decimal signs
-and possibly add a currency sign.
-
-To learn about value formatting, read documentation on :ref:`ui_persistence`.
-
-Table object does not contain any information about your fields (such as captions) but instead it will
-consult your Model for the necessary field information. If you are willing to define the type but also
-specify the caption, you can use code like this::
-
-    $table = $app->add('Table');
-    $order = new Order($db);
-
-    $order->addExpression('total', [
-        '[price]*[amount]',
-        'type'=>'money',
-        'caption'=>'Total Price'
-    ]);
-
-    $table->setModel($order, ['name', 'price', 'amount', 'total', 'status']);
-
-Column Objects
---------------
-
-To read more about column objects, see :ref:`tablecolumn`
-
-Advanced Column Denifitions
----------------------------
+Column Definition
+=================
 
 Table defines a method `columnFactory`, which returns Column object which is to be used to
 display values of specific model Field.
@@ -226,6 +182,66 @@ As a final note in this section - you can re-use column objects multiple times::
 
 This will result in 3 gap columns rendered to the left, middle and right of your Table.
 
+Calculated Fields
+=================
+
+Apart from adding columns that reflect currrent values of your database, there are several ways
+how you can calculate additional values. You must know the capabilities of your database server
+if you want to execute some calculation there. (See http://agile-data.readthedocs.io/en/develop/expressions.html)
+
+In the database - best performance
+----------------------------------
+
+It's always a good idea to calculate column inside datababase. Lets create "total" column  which will
+multiply "price" and "amount" values. Use ``addExpression`` to provide in-line definition for this
+field if it's not alrady defined in ``Order::init()``::
+
+    $table = $app->add('Table');
+    $order = new Order($db);
+
+    $order->addExpression('total', [
+        '[price]*[amount]',
+        'type'=>'money'
+    ]);
+
+    $table->setModel($order, ['name', 'price', 'amount', 'total', 'status']);
+
+In the model - best compatibility
+---------------------------------
+
+If your database does not have the capacity to perform calculations, e.g. you are using NoSQL with
+no support for expressions, the solution is to calculate value in the PHP::
+
+    $table = $app->add('Table');
+    $order = new Order($db);
+
+    $model->addField('total', [
+        'Callback', 
+        function($m) {
+            return $m['price'] * $m['amount'];
+        },
+        'type'=>'money'
+    ]);
+
+    $table->setModel($order, ['name', 'price', 'amount', 'total', 'status']);
+
+Alternative approaches
+----------------------
+
+.. warning:: Those alternatives are for special cases, when you are unable to perform calcualtion
+    in the database or in the model. Please use with caution.
+
+You can add add a custom code that performs formatting within the table through a hook::
+
+    $table->addField('no');
+
+    $table->addHook('beforeRow', function($table)) {
+        $table->model['no'] = @++$t->npk;
+    }
+
+To read more about column objects, see :ref:`tablecolumn`
+
+
 Table sorting
 =============
 
@@ -321,7 +337,7 @@ For most applications, however, you would be probably using internally defined m
 data stored inside your own database. Either way, several principles apply to the way how Table works.
 
 Table Rendering Steps
---------------------
+---------------------
 
 Once model is specified to the Table it will keep the object until render process will begin. Table
 columns can be defined anytime and will be stored in the :php:attr:`Table::columns` property. Columns
@@ -430,6 +446,71 @@ getDataCellHTML can be left as-is and will be handled correctly. If you have ove
 getDataCellHTML only, then your column will still work OK provided that it's used as a
 last decorator.
 
+Table Totals
+============
+
+.. php:attr:: totals_plan
+.. php:attr:: totals
+.. php:method:: addTotals()
+
+
+Table implements a built-in handling for the "Totals" row. Simple usage would be::
+
+    $table->addTotals();
+
+but here is what actually happens:
+
+ 1. when calling addTotals() - you define a total calculation plan.
+ 2. while iterating through table, totals are accumulated / modified according to plan.
+ 3. when table finishes with the rows, it adds yet another row with the accumulated values.
+
+.. important:: addTotals() will only calculate based on rendered rows. If your table has limit
+    or uses :php:class:`Paginator` you should calculate totals differently. See :php:meth:`Grid::addGrandTotals`
+
+Definition of a "totals plan"
+-----------------------------
+
+Each column may have a different plan, which consists of stages:
+
+ - init: defines the initial value
+ - update: defines how value is updated
+ - format: defines how value is formatted before outputting
+
+Here is the plan to calculate number of records::
+
+    $table->addTotals(['client' => [
+        'init'=>0,
+        'update'=>'increment',
+        'format'=>'Totals for {$client} client(s)'
+    ]);
+
+To make things easier to define, each stage has a reasonable default:
+
+ - init: set to 0
+ - update: 'sum' for numeric/money type and 'increment' otherwise
+ - format: will output '-' by default
+
+Also when calling addTotals() the column plan value does not have to be array, in which case the 'format'
+is set. The above example can therefore be shortened::
+
+    $table->addTotals(['client' => 'Totals for {$clients} client(s)']);
+
+Possible values for total plan stages
+-------------------------------------
+
+`init` value is typically a number, but can be any value, especially if you are going to control it's
+increment / formatting.
+
+`update` can be string - either "sum" or "increment". Other values are not supported. You can also pass
+a callable which gives you an option to perform update yourself.
+
+`format` uses a template in a format suitable for :php:class:`Template`. Within the template you can
+reference other fields too. A benefit for using template is that type formatting is done automatically
+for you.
+
+
+
+
 Advanced Usage
 ==============
 

docs/tablecolumn.rst

@@ -1,8 +1,9 @@
 
-.. _tablecolumn:
 
 .. php:namespace:: atk4\ui
 
+.. _tablecolumn:
+
 =======================
 Table Column Decorators
 =======================

src/Table.php

@@ -319,8 +319,6 @@ public function addTotals($plan = [], $plan_id = null)
             $plan_id = max(array_filter(array_keys($this->totals_plan), 'is_int'));
         }
 
-        //var_dump($this->totals_plan);
-
         return $plan_id;
     }
 
@@ -698,15 +696,15 @@ public function getTotalsRowHTML($plan_id)
             $title = '';
             if (is_string($plan[$name]['title'])) {
                 $title = $plan[$name]['title'];
+                $title = new Template($title);
+                $title = $title->set($totals)->render();
             } elseif (is_callable($plan[$name]['title'])) {
-                $title = call_user_func_array($plan[$name]['title'], [$totals, $this->model]);
+                $title = call_user_func_array($plan[$name]['title'], [isset($totals[$name]) ? $totals[$name] : null, $totals, $this->model]);
             }
 
             // title can be defined as template and we fill in other total values if needed
-            $title = new Template($title);
-            $title->set($totals);
 
-            $output[] = $column->getTotalsCellHTML($field, $title->render(), false);
+            $output[] = $column->getTotalsCellHTML($field, $title, false);
         }
 
         return implode('', $output);