Functions to Handle Special Forms Tool Events
You can use Groove Forms 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 while in Form design, 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 the system scripts in JavaScript.
Select the function that you want to implement from the function pull-down list and add the script code to the text block. You can implement the following system functions:
OnBeforeInitialize—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 has been 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 the 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 have been updated. If this script returns an exception, the inherited fields in the child records will be left unchanged.
OnAfterPropagateUpdates—called after all inherited fields in child records have been 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.
Note that these system functions are executed once for each record. For example, if you are printing a selection of records, OnBeforePrint and OnAfterPrint will be called for each record. If you are printing the selected record through a form, these functions will be called, but the OnAfterPrint function has no effect because the form is not displayed after the record is printed. If you are printing a view, these functions will not be called.
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 an OnBeforeSubmitData function. 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 will not created or updated and 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.