This chapter is from the book
This chapter is from the book
This chapter is from the book
Script Objects
So far, you have put all of your scripts behind form object events like the click event of a button or the initialize event of a text field. This is fine for short scripts that you don't need to reuse. However, when you start creating longer scripts that you can reuse in many different parts of your form, you'll want to write them in a Designer script object.
Script objects reduce your overall scripting efforts and make your forms easier to maintain by putting popular functions into one common location. In many cases, script objects also improve the performance of your forms based on the following two reasons:
- Scripting code rationalization: You can reduce the overall amount of JavaScript in your form by putting common functions in one location. This reduction decreases the file size of your PDF forms, which results in faster download times.
- Storage of commonly accessed data: It is very efficient to retrieve a data value from a script object, so you can use script objects to store commonly accessed data values. This improves the performance of forms that connect to external data resources and Web services.
The functions that you write in your script objects can only be written in JavaScript. If your script object is written to Run At Client, the calling script must also be set to Run At Client. The converse is also true. You will also write the calling script in JavaScript.
Creating a Script Object
It is very easy to create a script object; the programming challenge comes when you write the functions of your script object.
- Open the formObjectModel.pdf sample file.
- One script object called Validation is at the bottom of your Hierarchy palette (Figure 4.27).
Figure 4.27 The Validation script object in the formObjectModel.pdf file.
- To create a new script object, right-click on the order object at the top of your form hierarchy. Select Insert Script Object from the pop-up menu. A new script object appears below the Validation script object. You can create a script object at the form level (as you have done here) or at the subform level. To create a subform level script object, right-click on a subform object instead of the form object.
)
Writing Functions in Script Objects
After creating a script object, you can then add common functions to it. Select the script object in the Hierarchy palette and click your cursor in the Script Editor palette. There is no limit to the amount of functions that you can add to a script object or the amount of script objects that you can add to a form. You must write your functions according to the syntax and rules of JavaScript.
The Validation script object on the form provides common date validations that test any date entry on your form in a variety of ways including:
- Testing for real dates: A variety of tests can ascertain that a date entry is for a date that actually exists. These tests include logic that accounts for different month lengths and for leap years.
- Testing for future dates: These tests are valuable for birth date entries; you may not want to accept a birth date value that has not yet occurred.
- Testing for past dates: These tests are valuable for shipping date entries; you do not want to accept a ship date that has already past. The warehouse team would find this request to be rather challenging.
The Validation script object contains 216 lines of JavaScript, so you wouldn't want to replicate this in each Date/Time Field object on your form. The script object is organized into five functions that work together. The main function, dateValidation, calls each of the other functions. The following code shows the snippet of the dateValidation function that references the other functions.
function dateValidation(field, type){
[..]
flagYear = checkYear(nYear, currYear, field, type);
flagMonth = checkMonth(nMonth, currMonth, flagYear, field, type);
flagDay = checkDay(flagYear, flagMonth, nDay, nMonth, leapYear, field, type);
compareDay(flagDay, flagMonth, flagYear, nDay, currDay, field, type);
[..]
}
Referencing Functions in Script Objects
Now that you have an effective date Validation object, you just need to call it from the Date/Time objects on your form. Select the orderDate object on your form and go to the Script Editor. The script for calling the Validation script object is located in the exit event of the field:
Validation.dateValidation(this,2);
You reference script objects just like you reference other Designer objects by using a dot to indicate different levels of hierarchy. The first item is the script object (Validation) and the second item is the function (dateValidation). The function takes two parameters, which are in parentheses.
In this case, you pass two arguments to the script object. The first argument is the object that you are testing. The "this" keyword indicates that you will test the orderDate object. The second argument indicates the "type," which is represented by an integer value between 0 and 2. The type descriptions can be found at the top of the script object:
if type = 0 then any date can be entered as long as it is real if type = 1 then no future dates can be entered, only real dates allowed if type = 2 then no past dates can be entered, only real dates allowed