| Warning |
|---|
One key factors that makes Actionstep so powerful is the extent to which we allow our users to customize their systems. While most of our customization features don't require any understanding of programming or scripting languages, there are a few features within the program which allow you to manually manipulate things like HTML and PHP. These subjects are considered advanced topics and as such customers who use them should do so with the understanding that troubleshooting issues with HTML and PHP is outside of the scope of support. |
Calculated merge fields allow you to use a scripting language (PHP) to perform calculations. Creating calculated merge fields is an advanced topic and requires a some understanding of computer programming and in particular PHP. However it is fairly easy to create simple calculations by performing simple math on variables.
| Info |
|---|
Note for security reasons only a limited subset of the PHP commands are available. |
A calculated merge field is typically used when you need to add a new field to a document that is based on a calculation of existing fields. For example if you have designed a workflow for a property settlement you may need to calculate the rates apportionment on settlement day by dividing the amount already paid by how many days the new buyer will benefit from those rates after settlement day. This amount usually gets added to the final amount payable at settlement. This is easily achieved with a calculated merge field.
Table of Contents
Creating a new calculated merge field
From the top navigation bar go to Admin / "Document Templates" / "List of Merge Fields". This will show a list of all available merge fields in the system.
| Tip |
|---|
| Tip: If you just want to see existing calculated merge fields then filter the list on "Data Source" = "Calculated Field". |
...
As you saw in the previous examples you can use custom data fields in your expressions. To make this even easier there are two special variable names which give you direct access to single-row and multi-row data collection fields.
Accessing single-row data fields
| Code Block |
|---|
$singleRowData['data-collection-name']['data-field-name'] |
So in the date example above we could use this alternative syntax to access the settlement date:
| Code Block |
|---|
$settlement = date('Y-m-d', strtotime($singleRowData['conv_settlement']['settlement_date'])); |
Accessing multi-row data fields
| Code Block |
|---|
$multiRowData['data-collection-name'][0…n]['data-field-name'] |
...
Be aware for this to work you should use lower case when entering in the data collection name and the data field name.
Calculated Fields in repeat blocks
You can also use calculated merge fields within a repeat block if you are wanting to do calculations on values with the same instance. For example, if you are wanting calculate the GST on a line item in your invoice that is displayed in a repeat block you can use "$__rn" (note, two underscores) in the calculated merge filed to nominate the current repeat value.
You could use the option below:
| Code Block |
|---|
$incl = (floatval(str_replace(array('$', ','), '', '[[SPI_TotalIncl|$__rn]]')));
$excl = (floatval(str_replace(array('$', ','), '', '[[SPI_TotalExcl|$__rn]]')));
$Calc = $incl - $excl;
echo '$' . number_format($Calc, 2); |
Note that when you enter the calculated merge filed into your repeat block on your document template you should still add "rn=*" to it.