FormCalc Expressions (If and For)

In Designer, you can write scripts using one of two languages: FormCalc and JavaScript. If you’re like me, you’re more familiar with JavaScript because it’s very similar to Java and JScript syntax but when it comes to FormCalc, you’re lost. Well, not completely but you find it very difficult to find documentation on the syntax for loops (like While, For, etc.) which are sometimes essential. Maybe you fall-back on JavaScript in those times but, on average, *FormCalc scripts execute much faster* than JavaScript scripts so why not harness that performance in our forms?

In this post, I’ll explain the syntax of the *If* and *For* expressions in FormCalc. Those of you familiar with Visual Basic or VBScript will likely find this more familiar than the equivalent JavaScript syntax (while I’ll include for comparison however this isn’t a post on JavaScript syntax). In future posts, I’ll add to this collection by discussing the syntax for *While* and *ForEach* loops.


h2. ConventionsBefore we get started, I should explain a few things about the various syntax blocks you’ll find further down in this post (note that this is simplified for the purposes of this article):* [_SimpleExpression_]: A simple expression like a comparison “i >= 0″ that evaluates to true or false or a single entity like “MyVar” (a defined variable) or “5” (a number), for example.* [_ExpressionList_]: A set of 1 or more expressions, each on a separate line.* [_Square Brackets_]: A series of keywords (like “if”, “then”, “for”, “while”, etc.), SimpleExpressions and ExpressionLists grouped within square brackets denote an optional part of the syntax.* [_Asterisk Character_]: Sometimes a closing square bracket is followed by an asterisk (*). This indicates that the optional syntax may be used 0 or more times.* [_Question Mark Character_]: Sometimes a closing square bracket is followed by a question mark (?). This indicates that the optional syntax must be used 1 or more times.h2. VariablesI assume you’re probably familiar with declaring variables in scripts but just in case, in FormCalc, you declare variables like this:bc. var MyVarand you can even declare it and assign it a value in the same step:bc. var MyVar = 5h2. If ExpressionLet’s look at one of the most essential of all expressions:h3. FormCalc Syntaxbc. if ( SimpleExpression ) thenExpressionList[ elseif ( SimpleExpression ) thenExpressionList]*[ elseExpressionList]?endifBased on the syntax, you can do things like (assuming you’ve declared a variable named “i”):bc. if (i >= 10) theni = i + 10endiforbc. if (i >= 10) theni = i + 10elseif (i >= 5) theni = i + 5i = i * 2elsei = i + 1endifHopefully this illustrates the differences in the syntax indicated by the asterisk and question mark characters.h3. JavaScript SyntaxFor comparison, let’s look at the equivalent JavaScript syntax for the two examples above (note the semicolons and curly braces):bc. if (i >= 10)i = i + 10;orbc. if (i >= 10)i = i + 10;else if (i >= 5){i = i + 5;i = i * 2;}elsei = i + 1;h2. For ExpressionOften times, in your scripts, you need to execute some statements a certain number of times or iterate through a collection. In those cases (and many others), a For loop may be useful.h3. FormCalc Syntaxbc. for Variable = StartExpression(upto | downto) EndExpression[step StepExpression]?doExpressionListendforIn this syntax, there’s a _StartExpression_, and _EndEExpression_ and a _StepExpression_. These are all similar to _SimpleExpressions_ as described earlier. One thing to note about For loops in FormCalc is that “upto” loop will iterate as long as _Variable_ is less-than-or-equal-to (<=) _EndExpression_ whereas a “downto” loop will keep iterating as long as _Variable_ is greater-than-or-equal-to (>=) _EndExpression_. Also, the variable _Variable_ is implicitely declared in the For expression.Based on the syntax, you can do things like add the numbers 1 to 10, inclusively, to a list:bc. for i = 1 upto 10 doMyList.addItem(i)endforand thenbc.. var nCount = MyList.#items[0].nodes.lengthif (nCount >= 2) thenfor nItem = nCount downto 1 step 2 doxfa.host.messageBox( MyList.#items[0].nodes.item(nItem – 1) )endforendifp. which would display the value of each even-numbered list item in reverse sequence using a message box as long as there’s at least one even-numbered list item to display.h3. JavaScript SyntaxFor comparison, here are the equivalent JavaScript examples (note the semicolons and curly braces again):bc. for (var i = 1; i = 2){for (var nItem = nCount; nItem >= 1; nItem – 2){xfa.host.messageBox(MyList.resolveNode(“#items[0]”).nodes.item(nItem – 1) );}}