DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

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 = *
                                    }
                            }
                    }
            }
    }