Important note: all examples follow aTbRef naming conventions.
If you are starting here for cut-'n-paste samples, do take time to read this whole section. If new to action code functions, it will help to have a basic understanding of what functions do.
Basic example
A simple function might be written to return a number with an 18% tax uplift applied to the input number:
function fAddTax(iPrice){return(1.18*iPrice);};
or, split out only lines for clarity:
function fAddTax(iPrice){
return(1.18*iPrice);
};
Arguments arrive as String type data and Tinderbox coerces them as best it can. So here iPrice is a string value containing a number. However Tinderbox knows that if a number, e.g. 1.18 is multiplied by a String (containing a number) the String-type should be coerced to a Number-type before use and the resulting value will be Number data type.
Though more verbose, a safer approach—especially if unclear as to Tinderbox's coercion logic—is to be more specific, and insert comments, as shown below :
function fAddTax(iPrice){
// Arguments: iPrice - a number, the starting price
//
// make a variable (expected type of Number) and set it to argument #1
var:number vNum = iPrice;
// multiply variable by tax rate
vNum = 1.18 * vNum;
//return the tax-adjusted price
return vNum;
};
This defines a new function named 'fAddTax' that can be used in any action or expression (including ^action()^ in templates) to apply 18% tax to to the input figure, i.e. $1.00 → $1.18. It has one input argument, and returns a single value. Thus:
$MyNumber = fAddTax(500);
would set MyNumber's value to 1.18*500, i.e. 590. If we assume this is money, a $500.00 input becomes $590.00 including tax (be it US Dollars or any currency).
But hard-coding (i.e. 1.18) values like tax rates is generally considered bad practice as values can (will!) change. A better function might be this, comments, line breaks for for clarity:
function fAddTax(iPrice){
// Arguments: iPrice - a number, the starting price
//
// var:number vTaxRate = 1.18;
// make a variable (expected type of Number) and set it to argument #1
var:number vNum = iPrice;
// multiply variable by tax rate
vNum = vTaxRate * vNum;
//return the tax-adjusted price
return vNum;
};
But, supposedly fixed values like tax rates can change when governments change. So…
Adding an additional function argument
What if the tax rate changes? This can be accommodated by adding a second argument for the tax rate. Extra comments, line breaks for for clarity:
function fAddVarTax(iPrice,iTaxRate){
// Arguments:
// iPrice - a number, the starting price
// iTaxRate - tax rate percentage as a number (15 not 0.15)
// --------------
// make a variable (expected type of Number) and set it to argument #1
var:number vNum = iPrice;
// multiply variable by tax rate, assuming the tax rate input is a decimal percent, e.g. '0.18' for 18%
var:number vTax = iTaxRate;
vNum = (1 + vTax) * vNum;
//return the tax-adjusted price
return vNum;
};
Thus:
$MyNumber = fAddVarTax(500,20);
would pass a 20% tax rate, set MyNumber's value to 1.20*500, i.e. 600.
Further examples:
function fAnswer() {
return 42;
}
always returns 42. Or:
function fFibonacci(iNum){
if(iNum<2){
return (iNum);
};
return fFibonacci(iNum-1)+fFibonacci(iNum-2);
}
returns the iNumth Fibonacci number. This is a more advanced example showing the concept of recursion, whereby a function calls itself.
Using more concise code
For the experts who understand the flow of the code, the function defined above could equally well be defined in a terser form:
function fVarTax2(N,T){
return ((1+(T/100))*N);
};
Those with coding expertise my prefer this form. However, aTbRef code examples here are written assuming a reader with little or no coding expertise, thus the use of a more explicit and verbose format.
Next: Comments in functions