.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.

.. include:: ../../../Includes.txt

Calculate
^^^^^^^^^

The column/field on which this callback is applied shall be the result of a calculation? Maybe even based on other inputs from the same row? This is your interceptor. Define as many calculation steps as you want and choose from a variety of operations.

aStep
-----

Array. All the calculation steps sorted by its key. Every step is another array containing an operator (eOperator) and a value (nValue) and is applied to the foregoing result. For easier understanding consider the following example: ::

    'aStep' => array(
		'20' => array(
			'nValue' => '###nAmount###',
			'eOperator' => '*'
		),
		'10' => array(
			'nValue' => '###nPriceUnit###'
		),
		'30' => array(
		    'nValue' => 3,
		    'eOperator' => '+'
		)
	)

First of all, the calculation steps (the chain, so to say) is ordered by its keys - thus the new order is 10 (nPriceUnit), 20 (nAmount) and finally 30 (3). To start with 10, no operator is defined which means the default operator (+) is applied. The calculation itself starts with 0 and every step takes the last result as starting point. So the calculation would -- in this case -- look like the following:

- take *nPriceUnit*
- multiply it with *nAmount*
- add *3*

... or, in mathematical terms ... ::

    nPriceUnit * nAmount + 3

As you can see, mValue may either be a direct value (like 3), a column/field name marker (###nAmount###, ###nPriceUnit###) or even a marker for the well-known things (like ###GP:id###, ###tstamp###, ###date:Y### or ###fe\_user:uid###). The operator on the other hand might be one of the following (note that *position of mValue* tells you where in the calculation *mValue* and where the last result *x* are located):

========    =============   ======================= =========================================
Operator    Function        position of mValue      Example
========    =============   ======================= =========================================
\+          add             x \+ *mValue*           3 \+ 4 = 7
\-          subtract        x \- *mValue*           3 \- 4 = \-1
\*          multiply        x \* *mValue*           3 \* 4 = 12
/           divide          x / *mValue*            3 / 4 = 0,75
mod         modulo          x % *mValue*            3 % 4 = 3 (rest of division 3/4)
root        n\-th root      *mValue*\-th root of x  2nd root of 9 = 3; 3rd root of 64 = 4
pow         power           x ^ *mValue*            2 ^ 3 = 8
========    =============   ======================= =========================================

bDontForce
----------

Boolean. Allows the user to manually set the value on creation and thus prevent this callback handler from calculating. If set to true, the calculation is done only if the currently entered value is 0, empty, NULL or false.

Live calculation during form input
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This handler also allows it to calculate values on the fly and insert them into the form while the user inserts other values into the form. To explain this in more detail, imagine an order form where the user has to enter a price per piece and an amount while the system should calculate the total price.

What you need to do is to set the Calculate handler as an action handler and place it at the getFormValidation position. Since the calculator should calculate not only with single form fields, you also have to set data/bValidateAllValues to true. ::

    data {
        bValidateAllValues = 1
    }
    interception {
		Action {
			10 {
				eClass = Calculate
				sAction = getFormValidation
				sField = nPriceTotal
				aStep {
					10 {
						nValue = ###nPriceUnit###
					}
					20 {
						nValue = ###nAmount###
						eOperator = *
					}
				}
			}
		}
	}