Form events (client-side reference)

  • Article

 

Applies To: Dynamics CRM 2013

All Client-Side code is initiated by events. In Microsoft Dynamics CRM you will associate a specific function within a JavaScript library to be executed when specific events occur.

All form events have a user interface you use to specify one or more event handers. Each event handler specifies a single function within a JavaScript library and any parameters that can be passed to the function.

Events

OnLoad Event

OnSave Event

Field OnChange Event

Tab TabStateChange Event

IFRAME OnReadyStateComplete Event

Lookup Control PreSearch Event

OnLoad Event

The OnLoad event occurs after the form has loaded. It cannot prevent the window from loading. Use the OnLoad event to apply logic about how the form should be displayed, to set properties on fields, and interact with other page elements.

When the Microsoft Dynamics CRM for tablets client is disconnected, the OnLoad event is the only event that will occur.

Note

Forms for Updated entities do not reload the page after the initial save creating a record or any subsequent saves. Therefore the OnLoad event occurs only during the initial load of the form.

OnSave Event

The OnSave event occurs when:

  • The user clicks the Auto save icon button in the lower right corner of the form, even when there is no changed data to be saved.

  • Code executes the Xrm.Page.data.entity.save method, even when there is no changed data to be saved.

  • The user navigates away from the form and there is unsaved data in the form.

  • With auto-save is enabled, 30 seconds after data has changed and there is unsaved data in the form.

  • Code executes the Xrm.Page.data.save method and there is unsaved data in the form.

  • Code executes the Xrm.Page.data.refresh method passing a true value as the first parameter and there is unsaved data in the form.

To determine which button was clicked to perform the save, use the getSaveMode method.

You can cancel the save action by using the preventDefault method within the event arguments object. The preventDefault method which is accessible by using the 279ca720-e304-4e51-b99f-91722431c2c8#BKMK_GetEventArgs method that is part of the execution context. You must configure the form event handler to pass the execution context. For more information, see Use execution context and the form event pipeline.

Field OnChange Event

The OnChange event usually occurs when the data in a form field has changed and focus is lost.

Note

There is an exception to this behavior that applies to Two-Option (Boolean) fields that are formatted to use radio buttons or check boxes.

  • When Two-Option (Boolean) fields are formatted to use radio buttons, the OnChange event occurs immediately without requiring that the field lose focus.

  • When Two-Option (Boolean) fields are formatted to use check boxes, the OnChange event occurs immediately without requiring that the field lose focus except when the browser is Internet Explorer 8. In this case the control must lose focus before the OnChange event occurs.

This event also occurs when data changes on the server are retrieved to update a field when the form is refreshed, such as after a record is saved.

Using the Xrm.Page.data.entity attribute.fireOnChange method will also cause this event to occur.

The OnChange event does not occur if the field is changed programmatically using the setValue method. If you want event handlers for the OnChange event to run after you set the value you must use the Xrm.Page.data.entity attribute.fireOnChange method in your code.

All fields support the OnChange event. Data in the field is validated before and after the OnChange event.

Note

Although the Status field supports the OnChange event, the field is read-only on the form so the event cannot occur through user interaction. Another script could cause this event to occur by using the fireOnChange method on the field.

Tab TabStateChange Event

The TabStateChange event occurs when the DisplayState of the tab changes due to user interaction or when the setDisplayState method is applied in code. Use this event when you wish to change the src property of an IFRAME within the tab.

This event does not occur in CRM for tablets because tabs do not expand or collapse.

Note

If you set the IFrame. src property in the OnLoad event for an IFRAME within a collapsed tab, the value will be overwritten when the tab is expanded.

IFRAME OnReadyStateComplete Event

The OnReadyStateComplete event indicates that the content of the IFRAME has loaded and can be accessed in code. Use this event when referencing IFRAME controls within your scripts.

This event does not occur in CRM for tablets because IFRAMES are not supported.

Lookup Control PreSearch Event

The lookup control has a PreSearch event that occurs just before the control launches a dialog to search for records. Unlike other form events, the Form Editor does not provide a UI to set event handlers for this event. You must use the addPreSearch and removePreSearch methods on the lookup control to add or remove event handlers for this event.

Use this event with other Lookup control methods and events to change the results displayed in a lookup based on the form data current just before the lookup control shows search results for a user to choose from.

See Also

Form scripting quick reference
Write code for Microsoft Dynamics CRM 2013 forms
Use the Xrm.Page object model
Client-side programming reference