JavaScript
JavaScript is an object-oriented scripting language that provides interactive components such as mouse effects or field validation. Validation checks the data users have entered against specific criteria designers have set. When using Domino formulas to validate, the validation request has to be processed on the server and the error message (if any) rendered back to the browser. This is called roundtrip processing. One of JavaScript's benefits is that processing is done at the workstation level and not on the server. Processing at the workstation level improves performance because there does not have to be a roundtrip to the server, so network traffic is reduced.
Using JavaScript in Applications
JavaScript functions on different browsers, on Notes clients, and across platforms. JavaScript also does client-side processing. These two components of JavaScript give designers an easy, efficient way to code the client interface. JavaScript is best used for Web applications or if an application is being used on both clients.
JavaScript is coded in events listed in the Object tab, which vary depending on the design element being programmed. JavaScript can be used anywhere HTML is if the <SCRIPT LANGUAGE="JavaScript"> tag is used. By making it pass-thru HTML, Domino passes the code to browsers without interpreting the code. If designers want Notes clients to process HTML, they must make sure to check the Render pass through HTML in Notes in the Form Properties. Otherwise, designers must hide the HTML to prevent Notes from displaying it as text (you learn more about Hypertext Markup Language in “HTML,” later in this chapter).
The locations of resources and files on the Internet are identified individually by a Uniform Resource Locator (URL); you use a URL to address a resource or file you want to access across the Internet. JavaScript can also be placed in a URL:
<a href="javascript:code here">link text</a>
JavaScript is not a language choice in agents. However, agents can run JavaScript by using print statements that send the code to the browser as HTML. In LotusScript, Domino's proprietary, object-orientated programming language, the statements look like this:
Print "<SCRIPT LANGUAGE=JavaScript>" Print "JavaScript Code" Print "</SCRIPT>"
By setting the href property of the location object to the URL to open an agent, designers can run an agent through JavaScript. Here is an example:
window.location.href="/databasename.nsf/agentname?OpenAgent"
Modifying Simple JavaScript
JavaScript events are listed on the Objects tab in the Programmers Pane, as shown in Figure 16.2. Events are object sensitive, onBlur is available for Fields, and JS Header (which allows designers to enter JavaScript directly into the page header) is available on the Form. To program an object event, follow these steps:
Using JavaScript to Access Field Contents
To reference a field in JavaScript, designers must first understand the Document Object Model, which is discussed in more detail later in this chapter. When you reference an object, you must reference its parent first. A field's parent is a form whose parent is a document whose parent is a window. JavaScript must drill down through the Document Object Model to access a field's content, as in the following example:
Var variableName = window.document.forms[0].fieldname;
Most Domino fields map to JavaScript objects and can be referenced by their field names. However, there are a few differences between JavaScript and Domino that designers have to bear in mind, including the following:
JavaScript is case sensitive, and unlike Domino, JavaScript Field Name references are case sensitive.
JavaScript can access fields in Web and Notes clients when in edit mode.
In read mode, fields are never accessible to JavaScript in Notes clients. Fields are accessible in Web clients only if the Generate HTML for all fields option is selected in the Form Properties.
Hidden fields are never accessible to JavaScript in Notes clients. Hidden fields are accessible in Web clients only if the Generate HTML for all fields option is selected in the Form Properties.
FileUpload, an embedded object that allows Web clients to attach files, does not map to a Domino field type. FileUpload objects cannot be accessed in a Notes client.
Using JavaScript to Create a Redirect Page
Redirecting a page provides designers the ability to create dynamic user-friendly notifications that automatically return users to a set location. When a user submits a document, designers can program the $$Return field to display a “Thank You” message with a link to another page; or rather than display the link, designers can program the $$Return field to automatically redirect to another page after a few seconds. (You learn more about these fields in “Working with $$Return Fields,” later in this chapter.)
In the JSHeader event of the form, you can use the location property of the window object to write a function that relocates to an alternate page. Location allows the manipulation of URLs.
function newPage()
{
window.location=/pat relative to data/databaseName.nsf/pageName?OpenPage;
}
Now a timer needs to be set in the onLoad event of the form.
setTimeout('newPage()',milliseconds)
The timing is set in milliseconds, so if you want to delay redirection for 5 seconds, enter 5000 in place of milliseconds; 10 seconds would be 10000.
Another good utilization of redirect pages is for security reasons. If users try to circumvent your access by typing a URL to access a hidden view, for example, you can redirect them. Using a $$ViewTemplate for viewName form, designers can display a deny access message and apply the above redirection code to the $$ViewTemplate for viewName form, which would redirect users to a safe area. $$ViewTemplate forms are discussed in detail in Chapter 14, “Design Elements.”
Validating User Entered Data Using JavaScript
Input validation formulas, @Success and @Failure, work on the Web. Formulas are processed on the server, so the input validation formula makes a roundtrip to execute and render the information back to the Web. JavaScript validation's main benefit is client-side processing, which improves performance. JavaScript validation works for both Notes and Web clients. In JavaScript validation, only valid data makes the trip to the server; instant validation can be provided and the whole document doesn't have to be reloaded.
Validation can return an error message, return focus to the field, or change the value of the field. Validation can take place in the onBlur (exiting) or onFocus (entering) events. Users get instant per-field validations, one at a time, and designers can place focus back into the field that needs to be changed. Per-field validation can be bypassed and this is a major disadvantage to its use. If a cursor is not placed in the field, the event never happens.
Submit is another area where validation can take place. All fields are validated at one time and no validations will be missed. One disadvantage to validating at Submit is that, if multiple fields are being validated, users can be hit with multiple errors all at once.
Instead of returning focus to the field in question, a user-friendly way of validating is to offer a JavaScript prompt box for the users to enter missed information. The prompt box is executed before the submit is made and re-validates in case the client selects Cancel from the prompt. After doing the validation check on the field, set up the prompt as in this example:
promptMsg = "Please enter fieldName"; window.document.forms[0].fieldname.value = prompt(promptMsg,"");
Testing JavaScript
Unlike LotusScript, JavaScript does not have a built-in debugger. When you choose File, Save after writing JavaScript, or select the green check mark in the programmers' pane, JavaScript is compiled. If errors are detected, they are displayed, one at a time, in the status bar of the Programmer's Pane. JavaScript does not save as compiled code; it is recompiled every time it is run.
Understanding the JavaScript Document Object Model (DOM)
The Document Object Model (DOM) declares what objects are contained in the model and what objects can contain other objects. DOM also declares each object's list of methods, properties, and events.
 | LiveConnect enables JavaScript to access components (such as a Java applet) and manipulate them. Without knowing in what language the component is written, designers who know the API for the component can use JavaScript to drive that component. Netscape Navigator, Internet Explore, and Notes have LiveConnect capability. Be prepared to answer exam questions on this topic. |
When developing Web applications and implementing JavaScript, designers need to learn and understand the Document Object Model. JavaScript objects map to Domino design elements with some exceptions, as listed in Table 16.1.
| JavaScript Objects | Domino Design Elements |
|---|---|
| Window | Opened form, page, view, or frame that has focus. |
| Frame | Accessed by name as listed in the Frame Properties or as a frame array. |
| Document | Current opened Domino form, page, or view. |
A JavaScript Document object can contain the following Domino form, page, or view elements:
Applets (self-contained programs) array— Domino action bar, view, and Rich Text applets or applets you import.
Links array— Domino actions, link hot spots, and action hotspots. Domino link hot spots do not have events associated with them, but designers can add JavaScript code in the Other field on the <html> tab of the HotSpot properties.
Images array— Domino attachments, image resources, and pictures.
The preceding objects can be referred to by name if they are specified on the <html> tab of the object's properties box.
Forms array normally have only one element as Domino only renders one form at a time. Form arrays can be referenced two ways. One way is by their position in the array:
window.document.forms[0]
Another way is by the Domino form name preceded by an underscore:
window.document._formName
A forms array consists of an array of elements that can contain any of the following object types:
Button object— Domino buttons.
The button object can be referred to by name when specified on the <html> tab of the object's properties box.
Text object— Domino field types Text, Date/Time, Number, Names, Authors, and Readers.
Select object— Domino field types Dialog list, Listbox, and Combobox.
Hidden object— Domino hide-when is enabled and Generate HTML for all fields option is selected in the Form Properties.
The objects in the preceding list can be referred to by their respective Domino field names.
FileUpload object— Does not map to a Domino field type. FileUpload is an embedded object that allows Web clients to attach files and cannot be accessed in a Notes client.
Designers can display the JavaScript Document Object Model on the Design Client Welcome Screen by selecting it in the Show Me: drop-down box.
Working with Common JavaScript
Common JavaScript is new to Domino 6. Common JavaScript is applied to both Notes and Web users. Common JavaScript can be coded in seven events:
onFocus
onBlur
onChange
onLoad
onUnload
onSubmit
onHelp
These events are discussed in detail in the “Using JavaScript events in Domino” section of Chapter 14, “Exam 612—Design Elements.”