Standard HTML DOM Scripts

You can write functions that handle the standard HTML forms events. 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, which define event handlers for the DOM events, call the field-name_event functions, if they are defined in your script. The OnFocus, OnBlur, and OnClick functions are available for all fields except Contact, Rich Text, and Attachment. The OnChange function is available to all fields except Rich Text, Attachment, Options Buttons, and Check Box. For Options Button and Check Box fields, the OnFocus, OnBlur, and OnClick functions are available, but the OnChange function is not available. Note that these function names are case-sensitive; _OnFocus is the correct form but _onfocus will not work.

All HTML forms event functions (except for OnChange for Contact fields) have a single parameter that supplies the HTML field that triggers 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, you can only define an OnChanged function, which has two parameters that return IGrooveFormsToolContact values: the Contact specified after the change, and the original Contact value. 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 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. If the label has a space, the name has a "_32" instead. If two fields have the same label, the Forms tool appends a number to the duplicate field to generate a unique name. 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 and GetHTMLFieldValueAsNumber: Returns the current value of any HTML field on the form as a string. It does not work on Rich Text or Attachments fields. Note that GetHTMLFieldValue("PhoneNumber") is equivalent to document.GrooveFormBase.PhoneNumber.value.
• SetHTMLFieldValue and SetHTMLFieldValueAsNumber: Sets the value of any HTML field on the form to the specified string. It does not work on Rich Text or Attachments fields. 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 DOM script (such as adding fields 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.

Functions to Handle Special Forms Tool Events

Groove Forms allows you to implement system functions that are executed before or after the following events:

• Initialize: when a form is first displayed to the user.
• Terminate: when a form is about to close.
• Print: when the user is printing a single form (but not when the user is printing records from a view).
• SubmitData: when the user has added a new record or updated an existing one.
• PropagateUpdates: when inherited fields are updated in child records after data has been submitted for the parent record.

To implement a function for these events, go to the Form Scripts tab of Modify Form, select "System callouts scripts for form-name.js" and click the Modify button. The Forms tool designer assigns a script name and the language is set to JavaScript. You can only program these system scripts in JavaScript.

Select the function to implement from the function pull-down list, and add the function code to the text block. These functions do not take any parameters. You can implement the following system functions:

• OnBeforeInitialize: this function is called before the forms fields have been initialized from the record. When this function is called, the correct status information is available from the global functions, such as GetIsNew and GetIsReadOnly.
• OnAfterInitialize: called after the forms fields have been initialized but before control is returned to the user.
• OnBeforeTerminate: called before the form is removed.
• OnAfterTerminate: called after the form is removed from the screen but before the Forms tool navigates to the next item.
• OnBeforePrint: called before the form is printed. You can modify the form in this function to improve the appearance of the printed form.
• OnAfterPrint: called after the form is printed. You can return the form to original state after modifying it for printing.
• OnBeforeSubmitData: called before the Forms tool adds or modifies the underlying record.
• OnAfterSubmitData: called after the Forms tool adds or modifies the record, but before the Forms tool navigates to the next item.
• OnBeforePropagateUpdates: called after OnAfterSubmitData, when the parent record has been updated, but before any inherited fields in child records are updated. If this script returns an exception, the inherited fields in the child records are unchanged.
• OnAfterPropagateUpdates: called after all inherited fields in child records are updated.

A system script can call a function that is defined in another script file, but that file must be selected for use with the form.

If a system script returns a false value, the Forms tool does not complete the action. For example, your script can perform a final validation in a OnBeforeSubmitData. If the values specified do not pass, you can display a message in a message box or in the status bar and return false. The record is not created or updated; the user can correct the data and then resubmit it. You should not return a false in an OnBeforePrint or OnAfterPrint function; the form display may not be correctly restored. Returning false has no effect in the OnAfterInitialize, OnBeforeTerminate, OnAfterTerminate, and OnAfterPropagateUpdates functions; consequently, you should not return false in these functions.

Accessing Context Information

You can access information about the form, access the data in the underlying record, and access a limited number of Groove services. This access is provided by global functions, including the following.

• GetApp: provides access to the Forms Tool UIDelegate, which provides access to the Groove runtime environment and to Groove services. For example, you can use GetApp to find the members of the workspace, send instant messages, and open transactions to lock the workspace while you are accessing a record.
• GetFormRecord: returns the current form record
• GetIs* Functions: provide context information, such as whether the form is readonly, is a response, or is being viewed in the preview pane.

Functions to Provide Initial Values for Form Fields

You can perform custom field initialization by defining a function that is used to provide the initial value for a field. To initialize a field using a function, you follow these steps:

• Define the function in a Form script. The function should return a value with the same type as the field, which is used to initialize the field.
• Associate the script with the form by ensuring that the script's Check Box is checked in the form's list of scripts.
• Create a new field or modify an existing field, select Initial Value from the Field Properties form and select Function from the Drop Down list.
• Enter the function reference in the initialization data field. You can specify any parameters in the function reference that you could in a script.

When a new form is created, the field is initialized by executing the function.

If a field gets its initial value from a function and the function is not defined when the new record is created, the Forms Tool displays a script error. If you include a field that is initialized by a function in more than one form, you must ensure that the script that defines the function is associated with each form that includes the field.

Whew. Finally, let's pull all this together into a useful example. The following code sends an instant message to all members of the space except the current author when the user clicks on a button.

function SendIMButton_OnClick(i_objInput)
{
  try
  {
    var app=GetApp();

    // Put up Dialog message
    var userText = app.DisplayTextInputDialog("Message text",
    "Send instant message to other workspace members with link to this record");

    if (userText.Result ==1)
    {
      // send message
        var URLArray = new Array();
        var index=0;
        var MemberNameURLEnum= app.CreateMemberNameURLEnum();
      while (MemberNameURLEnum.HasMore())
      {
        var MemberNameURLPair = MemberNameURLEnum.OpenNextPair();
        if (MemberNameURLPair.first != app.CurrentAuthorName)
        {
          // if not current user, add URL to array
          URLArray[index++]=MemberNameURLPair.second;
        }
      }
      var URLEnum = CreateBSTREnumFromArray(URLArray)
      app.SendInstantMessage(URLEnum, userText.Data, true, true);
    }
    // if not = 1, user clicked cancel, do nothing    

  }
  catch (error)
  {
    GetApp().DisplayError("An error has occurred: " + error.description
    + "[" + error.number + "]");
  }
}