Calculator forms: Special fields

Calculator forms can have special fields allowing very flexible configurations.

Hidden field

A hidden field definition looks like:

  fieldName @=hidden ==initialValue

Any other properties are ignored, but you can add a label to indicate to editors what this field is about.

The field is added to the form and its value can be read or set, but nothing is shown in the page.

In hidden fields you can place constants or intermediate values, especially if you're using formulas.

Note that fields are calculated in the order they appear in the form, so a field holding an intermediate value should be placed before fields that use that value.

Variable "toPrecision" field

You can define the global precision for the results (rounding to a number of decimal digits) in the form creation page, and the precision for individual fields, but you can also let the user / visitor select the precision.

This is done with a special field named "toPrecision" in your form, and can be either a "number" field, or a "checkbox" field.

For a number field, use something like this:

toPrecision @=number3 ==2 >=0 <=8 ?=Precision (decimal digits)

This will make a short numeric field that can be modified between 0 and 8, initially 2, and the results will be rounded to that number of decimal digits.

For a checkbox field, use something like this:

toPrecision @=checkbox ==2 ?=Round results

This will make a checkbox with the predefined value of 2; when the user checks it, the results will be rounded to 2 decimal digits. When it is unchecked, the results are not rounded.

Table field

A Table field has the following properties:

tableName @=table ?=Header|Cells|On|Top ^=First|Column|Cells

The ?=Label property contains the header (first row) cells, separated by the vertical bar "|".

The ^=Prefix property contains the first column cells, separated by the vertical bar "|".

The above field definition will create a table like this:

Header	Cells	On	Top
First	$$.tableName_1_1	$$.tableName_1_2	$$.tableName_1_3
Column	$$.tableName_2_1	$$.tableName_2_2	$$.tableName_2_3
Cells	$$.tableName_3_1	$$.tableName_3_2	$$.tableName_3_3

The individual cells can be referred to in the calculation logic the following way:

  $$.tableName_ROW_COLUMN or $$['tableName_ROW_COLUMN']

where tableName is the name of the field (first on the line), ROW is the cell row number, and COLUMN is the cell column number, starting from 1, not including the header row and the first column.

For example, to set the value of the 2nd cell on the 3rd row, you would do something like:

$$.tableName_3_2 = 123.45; // or
$$['tableName_3_2'] = 123.45;

Note that table cells cannot be set by defining local variables tableName_3_2, you need to use the "$$" object $$.tableName_3_2.

A table doesn't have a "Label" property since it is used for the header. If you need to add a label before the table, add a "Note" (just text without any property separators).

Sample form using a table

Field definitions:
numbA >=0 ==47 ?=Students '''from Group A''' passA >=0 ?=Passed exam numbB >=0 ==31 ?=Students '''from Group B''' passB >=0 ?=Passed exam @=copy @=reset stats @=table ?=Groups|Numbers|Passed exam|Success rate ^=Group A|Group B|Totals

Calculation logic:
$$.stats_1_1 = numbA; $$.stats_2_1 = numbB; $$.stats_3_1 = numbA + numbB; $$.stats_1_2 = passA; $$.stats_2_2 = passB; $$.stats_3_2 = passA + passB; $$.stats_1_3 = percent(passA/numbA, this.toPrecision); $$.stats_2_3 = percent(passB/numbB, this.toPrecision); $$.stats_3_3 = percent((passA + passB)/(numbA + numbB), this.toPrecision);

And here is the actual working form:

If you have any questions or difficulties, please let us know.

HTML fields

This is an advanced field, creating it requires knowledge of HTML.

fieldName @=html creates an HTML division block where you can have almost any content.

If your form has HTML fields, your function will be called after the form creation, and the active variable will have the value "onCreate". So your function should set the $$.fieldName value to the markup that is to appear in the division block:

if(active == 'onCreate') {
  $$.fieldName = 'Your HTML code';
  return $$; // to avoid using "else"
}

Within the HTML, you can have additional fields or simply placeholders where your results can be displayed. To enable such fields, add to them data-role attributes with their variable names.

For example, if your HTML has the following field:

<span data-role="myCustomFieldName"></span>

Then in your calculation function you can set this value like this:

$$.myCustomFieldName = "Some value";

Note that custom fields cannot be set by defining local variables "myCustomFieldName=value;", you need to use the "$$" object "$$.myCustomFieldName=value;" instead.

Config field

A config field definition looks like:

  configEntry @=config  ==configValue

This allows for the form to define some library configuration options, for example toDecimal or toPrecision (to be documented in the future).

Any other field properties are ignored and nothing is shown in the page.