Standard HTML DOM Scripts for Groove Forms

You can write functions that handle the following HTML forms events:

• OnBlur

• OnChange

• OnClick

• OnFocus

Functions are named by using a prefix of the field's name followed by an _ (underscore) and then the event name. For example, if you have a field named Category, you could define Category_OnFocus, Category_OnClick, and Category_OnChange functions. The Forms tool defines event handlers for the DOM events and these call the field-name_event functions, if they are defined in your script. Note that these function names are case-sensitive; _OnFocus is the correct form but _onfocus will not work.

The following table identifies the event functions that are available for each field designer type.

Designer Type	OnBlur	OnChange	OnClick	OnFocus
Text	Available	Available	Available	Available
Multi-line Text	Available	Available	Available	Available
Number	Available	Available	Available	Available
Unformatted Number	Available	Available	Available	Available
Currency	Available	Available	Available	Available
Date	Available	Available	Available	Available
Date Time	Available	Available	Available	Available
Drop-down List	Available	Available	Available	Available
List Box	Available	Available	Available	Available
Options Button	Available	Unavailable	Available	Available
Check Box	Available	Unavailable	Available	Available
Password	Available	Unavailable	Available	Available
Contact	Unavailable	Available	Unavailable	Unavailable
Script Button	Unavailable	Unavailable	Available	Unavailable
Rich Text	Unavailable	Unavailable	Unavailable	Unavailable
Attachments	Unavailable	Unavailable	Unavailable	Unavailable
Form Heading	Unavailable	Unavailable	Unavailable	Unavailable
Section Heading	Unavailable	Unavailable	Unavailable	Unavailable
Horizontal Line	Unavailable	Unavailable	Unavailable	Unavailable
Static Text	Unavailable	Unavailable	Unavailable	Unavailable
Image	Unavailable	Unavailable	Unavailable	Unavailable

All HTML forms event functions except for OnChange for Contact fields have a single parameter that supplies the HTML field that is triggering the event. For example, you could define the following functions for a text box field named Organization:

function Organization_OnFocus(i_objInput) {}
function Organization_OnBlur(i_objInput) {}
function Organization_OnChange(i_objInput) {}

However, with fields of type Contact, the OnChange function is called with two parameters: the first is an IGrooveFormsToolContact of the new Contact, and the second is an IGrooveFormsToolContact with the original Contact. You can define the following function for a Contact field named PMContact:

function PMContact_OnChange(i_Contact, i_OriginalContact) {}

If you add a Script Button field to a form, the Forms tool calls the function named field-name_OnClick, by default. You can explicitly set the name of the OnClick function when you define or modify the field in the Forms Designer. You can give this function any name except that it cannot have the same name as the Script Button field itself or any other field name. If the OnClick function and Script Button do have the same name, clicking on the button causes a script error.

If you do not specify the Name property when you add a new field to a form, the Forms Designer generates a name based on the label. Generated field names are encoded, and any non-alphanumeric characters will be encoded. For example, if the label has a space in it, the name will include "_32" in its place. If you have two fields with the same label, the Forms tool will append a number to the duplicate field to generate a unique name. If you want to have shorter field names in your script, specify the Name property when you create the field. Once you have created the field, you cannot change the Name property.

You can access the fields on a form using the following global functions or using standard DOM scripts.

• GetHTMLFieldValue, GetHTMLFieldValueAsNumber, and GetHTMLFieldValueAsDate—Return the current value of any HTML field on the form. They do not work on Rich Text or Attachments fields. GetHTMLFieldValue returns a string, GetHTMLFieldValueAsNumber returns an int, and GetHTMLFieldValueAsDate returns an int that represents the date in milliseconds since January 1, 1970. Note that GetHTMLFieldValue("PhoneNumber") is equivalent to document.GrooveFormBase.PhoneNumber.value.

• SetHTMLFieldValue, SetHTMLFieldValueAsNumber, and SetHTMLFieldValueAsDate—Set the value of any HTML field on the form to the specified value. They do not work on Rich Text or Attachments fields. SetHTMLFieldValue takes a string for the value, SetHTMLFieldValueAsNumber takes an int, and SetHTMLFieldValueAsDate takes an int that represents the date in milliseconds since January 1, 1970. Note that SetHTMLFieldValue("PhoneNumber", "999-888-7777") is equivalent to document**.GrooveFormBase.PhoneNumber.value= "999-888-7777"**.

• EnableField and DisableField—Enables or disables a field.

• HideField and ShowField—Hides the field from view or displays the field on the form.

When accessing the form, you can use the name GrooveFormBase or forms[0]. They are equivalent. You can get the value of a field from the form or from the document by ID. The following JavaScript statements are equivalent; they all return the value of the PhoneNumber field:

  document.forms[0].PhoneNumber.value
  document.GrooveFormBase.PhoneNumber.value
  document.getElementById("PhoneNumber").value

If you are dynamically updating the form layout in your script, such as by hiding, showing, adding, or moving fields, you should call the global RefreshErrorIcons function defined in PublicScript.js. If you do not call this function, The Forms tool may display some warning icons in the incorrect locations. Typically, these warning icons indicate to the user that they have entered an illegal value in the field or omitted a required field.

Your script should not replace any of the DOM event handlers defined by the Forms tool by overloading the function. If you do overload any of these functions, the Forms tool may not execute correctly.

Note

You have limited access to Rich Text fields on the form and no access to Attachments fields on the form. You can only use Rich Text fields in the AppendLinksToRichTextField method.

See Also

Concepts

Using Scripts in the Groove Forms Tool