FormCalc and JavaScript
LiveCycle Designer supports scripting in two languages: FormCalc and JavaScript. A form can use both languages at the same time, but you cannot mix the two languages in one object event. FormCalc is an easy-to-use calculation language that Adobe developed for use in XFA forms. It is very similar to calculation language that you use in a spreadsheet program like Microsoft Excel. JavaScript, on the other hand, is a powerful, object-oriented scripting language that many programmers are already familiar with. This book focuses on JavaScript but also includes a few FormCalc examples.
FormCalc
FormCalc is not as powerful or as ubiquitous as JavaScript. However, it is ideal for nonprogrammers who need to add calculations to their forms. If you come from a Microsoft Excel background and you don't have any JavaScript experience, you should consider using FormCalc. FormCalc has many built-in functions that cover a range of areas including finance, logic, dates/times, and mathematics. FormCalc is supported in Designer, Acrobat, Reader, and in the LiveCycle Servers. However, it will not work with the HTML forms created by LiveCycle Forms.
Like Excel, most FormCalc scripts are only one line long. The following code sets the rawValue property of TextField1 to the sum of (1,2,3,4), which is 10:
form1::ready:form - (FormCalc, client) ---------------- TextField1.rawValue = Sum(1,2,3,4)
The first line of code is a script header that gives you important information about your script. The first part indicates that the script is running in the form:ready event; the second part shows you that the language is FormCalc and the script is running on the client. These headers are also used when you are working with JavaScript.
Date and time functions
FormCalc has many functions that are ideal for the common tasks that interactive forms require. For instance, the following script sets a Date/Time Field to the current date:
form1::ready:form - (FormCalc, client) ---------------- // Today's Date in long-style date format. DateTimeField1.rawValue = num2date(date(), DateFmt(3))
The second line is a script comment and will be ignored by the script interpreter. You can add a comment line to your FormCalc or JavaScript code by beginning the line with two slashes "//". You can also add a comment line to a FormCalc script by preceding it with the semicolon ";" symbol. Additionally, you can add a comment block to your JavaScript code by beginning the block with the "/*" characters and ending it with the "*/" characters.
Financial functions
If you are working on financial forms, FormCalc has many built-in financial functions that you can add to your form. For instance, it is easy to calculate the APR (annual percentage rate) of a loan with FormCalc. In the following example, the principal amount of the loan is $35,000, the monthly payment amount is $269.50, and the total amount of months is 360. This script returns an annual percentage rate of 0.08515404566 to TextField1:
form1::ready:form - (FormCalc, client) ---------------- TextField1.rawValue = Apr(35000, 269.50, 360)
Adding FormCalc to your forms
To see FormCalc in action, open a blank form and add a Text Field and a Button object. Follow these steps to add a FormCalc script to each of your objects.
- Select the Text Field object and select the form:ready event in your Script Editor (Figure 4.2).
Figure 4.2 Inserting a built-in FormCalc function into your script.
- Click on the script editing field to create a blinking "I" beam. While in this mode, select the Functions button and select the Concat(s1[,s2...]) function (Figure 4.2). Double-clicking this item inserts the Concat function into your script.
- Complete your script by adding a reference to your Text Field object's rawValue property:
form1::ready:form - (FormCalc, client) ---------------- TextField1.rawValue = Concat("Live", "Cycle")
The Concat function in FormCalc returns the concatenation of two or more strings. In this example, the Concat function joins the string "Live" with the string "Cycle" to form the word "LiveCycle." This new value is assigned to the rawValue property of the text field. You can use string functions like Concat in your forms to join a user's first name with his last name to create a full name value. - Select the Button object and add the following code to the click event:
form1.#subform[0].Button1::click: - (FormCalc, client) -------- $host.messageBox("Hello, World!")
When you click this button, a pop-up message box with the phrase "Hello, World!" appears. The "$host" item is a FormCalc shortcut that represents the host object. To reference the host object in JavaScript, you use the following syntax:form1.#subform[0].Button1::click: - (JavaScript, client) -------- xfa.host.messageBox("Hello, World!")
This chapter will cover more about the host object and the other object models in XFA forms. If you are interested in exploring FormCalc further, Adobe has included excellent reference materials in the Help section including the "FormCalc User Reference," which you can find under the Scripting section of the Help System.
JavaScript
Although FormCalc is the default scripting language in Designer, JavaScript is more ideal for creating sophisticated interactive and dynamic forms. The following are some of the advantages of using JavaScript.
- JavaScript is ubiquitous. It is very likely that you will be able to leverage your organization's existing JavaScript knowledge because JavaScript is a scripting standard that many programmers and designers already know.
- JavaScript is object-oriented. You can create JavaScript objects and custom functions, and use them throughout your form. This feature of JavaScript is not available in FormCalc, and it enables you to eliminate work by allowing you to reuse your code.
- 50,000 JavaScript fans can't be wrong. Because JavaScript has been a scripting standard for a long time, you will be able to find sample scripts for almost everything you need to do. You can find these sample scripts on the Web, in JavaScript books, and in this book.
- JavaScript works for PDF and HTML forms. If you are creating XDP files that you want LiveCycle Forms to render as both PDF and HTML forms, you must use JavaScript.