# Calctastic v1.0 (2004-Apr-23)

## What is Calctastic?

The Calctastic JS library allows you to place a few simple formulæ on your page, and have the burden of trapping events and running those formulæ taken care of for you. (Think Excel, but more powerful.)

Calctastic supports cascading formulæ (performing as few udpates as possible). It supports circular references. It provides automatic formatting options, while maintaining internal precision beyond what may be displayed. It can use just about any item on the page as a source or destination for values. Hell, Calctastic even washes your stinky socks for you.

Calctastic has been tested to work with IE6, Firefox, and Safari, and is free.

Before getting to the "How do I use it?" part, let's look at a few examples.

## Example 1 - Simple Formula

``AddFormula('finalprice','Val(itemprice)*Val(quantityOrdered)');``

``````AddMultiple('subtotal','Val(price)*Val(qty)',1,3);
``````
Item Price Qty Total
Total + 0(tax) = 0
DVDs 24.99
Donuts 3.15 0
Cats 115 0

Tax Rate:

## Example 3 - Circular References

``````AddFormula('x','4*Val(y)');

/ 4 =

## Example 4 - Extended Precision

``````AddMultiple('precision_subtotal','.142 * 2',0,2);

.142 * 2 = (display rounded)
.142 * 2 = (display rounded)
.142 * 2 = (display rounded)
Sum: (sum of displayed values)
Sum: (sum of internally precise values)

## Sweet! How do I use it?

First, you have to download two JS files (genlibsubset_calctastic.js & calctastic.js) and include them in your page.

Next, put a unique ID on every element on the page you want to get values from or set to display a value.

Finally, use the `AddFormula` and `AddMultiple` functions to define your formulæ for the page.

...

What, that wasn't enough information for you? OK, here's some documentation about the functions you can use:

`AddFormula( destID, formula )`

`destID` — a string with the value to set to the result of the formula.
`formula` — a string defining the formula, using JS code.

Example: `AddFormula( 'total' , 'Val(piece1) + Val(piece2) * Math.pow( Val(piece3) , 2 )' );`

The `formula` string uses standard Javascript syntax and functions. Use the following special functions (see below) to draw values from other fields: `Val()`, `ValRounded()`, `Sum()`, `SumRounded()`, `Avg()`, `AvgRounded()`, `Min()`, or `Max()`.

`AddMultiple( destIDBase, formula, starNum, endNum )`

`destIDBase` — a string representing the beginning of a field id.
`formula` — is a string defining the formula (see AddFormula).
`starNum` — an integer representing the first field number to use.
`endNum` — an integer representing the last field number to use.

Example: `AddMultiple('subtotal','Val(price) * Val(quantity)',0,5)`

This function is a convenience shorthand for adding multiple formulæ which are all similar. The example above is equivalent to:

``````AddFormula('subtotal0','Val(price0) * Val(quantity0)');
`Val( fieldID )` - get the precise value of a field.
`ValRounded( fieldID )` - get the displayed value of a field.

`fieldID` — the ID of the field to use, without quotes.

Example: `AddFormula('total','Val(price) * Val(quantity)')`

Note that text inputs which have formatting applied will never be more precise than what is displayed. For example, if the user types "2.6" into an input which is set to format as an `integer`, the input will be changed to read "3" and the 'precise' value returned by `Val` will also be "3".

See Example 4 for a demonstration of precise vs. rounded values.

`GVal( fieldID )` - get the precise value of a field.
`GValRounded( fieldID )` - get the displayed value of a field.

For use inside AddMultiple; performs the same function as Val and ValRounded, except that the field ids are not 'expanded'.

Example: `AddMultiple('withTax','Val(subtotal) * GVal(taxRate)',0,3)`

The following commands are equivalent to the example above, and show the difference between `Val` and `GVal`:

``````AddFormula('withTax0','Val(subtotal0) * Val(taxRate)');
`Sum( baseFieldID , startNum , endNum )` - add together multiple precise values.
`SumRounded( baseFieldID , startNum , endNum )` - add together multiple displayed/rounded values.

`baseFieldID` — the base ID of the field to use, without quotes.
`starNum` — an integer representing the first field number to use.
`endNum` — an integer representing the last field number to use.

Example: `AddFormula('grandtotal','Sum(subtotal,0,3)')`

This is a convenience function for adding multiple values. The above example is equivalent to the following:

``AddFormula('grandtotal','Val(subtotal0)+Val(subtotal1)+Val(subtotal2)+Val(subtotal3)');``
`Min( baseFieldID , startNum , endNum )` - find the smallest of a group of numbers.

`baseFieldID` — the base ID of the field to use, without quotes.
`starNum` — an integer representing the first field number to use.
`endNum` — an integer representing the last field number to use.

Example: `AddFormula('cheapestprice','Min(price,0,3)')`

This is a convenience function for doing a minimum on multiple values. The above example is equivalent to the following:

``AddFormula('cheapestprice','Math.min( Val(price0),Val(price1),Val(price2),Val(price3) )');``
`Max( baseFieldID , startNum , endNum )` - find the largest of a group of numbers.

`baseFieldID` — the base ID of the field to use, without quotes.
`starNum` — an integer representing the first field number to use.
`endNum` — an integer representing the last field number to use.

Example: `AddFormula('heaviest','Max(weight,0,3)')`

This is a convenience function for doing a maximum on multiple values. The above example is equivalent to the following:

``AddFormula('heaviest','Math.max( Val(weight0),Val(weight1),Val(weight2),Val(weight3) )');``

## What was that about automatic formatting?

Putting the following CSS classes on items used as output (or text input) for formulæ will cause them to be automatically formatted:

`class="integer"`
Round the number to the nearest integer and insert commas as appropriate. 1024.568 → "1,025"
`class="currency"`

Put a leading '\$' on the value, round the number, and add commas as appropriate. 1024.568 → "\$1,025"

When used with `class="currency dec2"` rounds to cents (two decimal places). 1024.568 → "\$1,024.57"

(Any value may actually be used for `class="currency decn"` to round to specific number of decimal places.)

`class="float"`

Performs no special formatting on the number, but rounds it to the number of places specified by `class="decn"`.

(Any value may be used for `class="float decn"` to round to specific number of decimal places.)

`class="percent"`

Multiply by 100, round the number, and add a percent symbol. 0.06275 → "6%"

(Any value may be used for `class="percent decn"` to round to specific number of decimal places. For example, `class="percent dec1"` turns 0.06275 → "6.3%")

Note that input values displayed as `percent` are internally maintained as the /100 number. So, while the input may display "6%", the Val function will return 0.06 as the value.

## Simple Examples

The following are on their own pages to make it really easy to see how easy using Calctastic is.

## Some random notes/tips

• As demonstrated in Example 2, it's possible to create a formula that sets a 'field' which doesn't correspond to any element on the page (`tmp_pretax` in the example), and then refer to that value in later formulæ.
• It doesn't matter what order you put your `AddFormula` and `AddMultiple` calls in. The library will figure out which fields depend on each other and update them in the proper order.
• All formulæ you specify will be computed once as the page loads, and all (visible) fields that are referenced in them (either as destinations or sources for a formula) which are using auto formatting will be formatted.