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)');



Example 2 - Auto-Formatting; Cascading Formula; Grid Navigation

AddMultiple('subtotal','Val(price)*Val(qty)',1,3);
AddFormula('tax','Val(tmp_pretax)*Val(taxrate)');
AddFormula('grandtotal','Val(tmp_pretax)+Val(tax)');
AddFormula('tmp_pretax','SumRounded(subtotal,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)');
AddFormula('y','Val(x)/4');

/ 4 =

Example 4 - Extended Precision

AddMultiple('precision_subtotal','.142 * 2',0,2);
AddFormula('prec_actualsum','Sum(precision_subtotal,0,2)');
AddFormula('prec_roundedsum','SumRounded(precision_subtotal,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)');
AddFormula('subtotal1','Val(price1) * Val(quantity1)');
AddFormula('subtotal2','Val(price2) * Val(quantity2)');
AddFormula('subtotal3','Val(price3) * Val(quantity3)');
AddFormula('subtotal4','Val(price4) * Val(quantity4)');
AddFormula('subtotal5','Val(price5) * Val(quantity5)');
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)');
AddFormula('withTax1','Val(subtotal1) * Val(taxRate)');
AddFormula('withTax2','Val(subtotal2) * Val(taxRate)');
AddFormula('withTax3','Val(subtotal3) * 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