Use form and field events

  • Article

 

Applies To: Dynamics CRM 2013

You can add scripts for the OnLoad and OnSave events for forms and OnChange events for each field. Tabs have a TabStateChange event and IFRAMES have an OnReadyStateComplete event. The PreSearch event is new with Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online. Handlers for this event can only be applied using code for lookup field controls.

Note

Events in the form are disabled for the bulk edit form. The bulk edit form is displayed when multiple records in a list are edited.

In This Topic

OnLoad event

OnSave event

OnChange event

TabStateChange event

OnReadyStateComplete event

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 prepare the data in the form for use. Actions that can be performed by using the OnLoad event include the following:

  • Perform calculations based on changing values.

  • Alert a user to a situation.

  • Disable fields that shouldn’t be updated.

More information: OnLoad Event

OnSave event

The OnSave event does not correspond to the standard HTML OnSubmit 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 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.

You can detect which action was performed to save the form by using the getSaveMode method in the save event arguments retrieved from the 279ca720-e304-4e51-b99f-91722431c2c8#BKMK_GetEventArgs method execution context. Navigating away from a form when it contains unsaved data corresponds to the “Save and Close” behavior found in forms for entities that haven’t been updated.

The OnSave event can be canceled to prevent the data from being saved. Because of this it, is very common to use the OnSave event to validate data.

More information: OnSave Event

OnChange event

The OnChange event is available on every field. Generally, the OnChange event requires two conditions to be true:

  • The data in the field must change.

  • The field must lose focus.

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 option, or 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 doesn’t 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 fireOnChange method in your code.

After the event, the data in the field will be revalidated. This means that you can’t use the event to enter invalid data.

Actions that can be performed by using OnChange include the following:

More information: Field OnChange Event

TabStateChange event

This event occurs when a tab is expanded or collapsed. You may want to defer execution of code until a tab is expanded.

Note

This event never occurs in Microsoft Dynamics CRM for tablets because tabs in that client don’t collapse.

This event is important if you use script to modify the src property of an IFRAME control. An IFRAME will be refreshed when the tab is expanded. Any changes to the src property will be removed. If you interact with the src property of an IFRAME, you should always include this code in the TabStateChange event instead of the Onload event.

More information: Tab TabStateChange Event

OnReadyStateComplete event

Any script that interacts with an IFRAME will fail unless the contents of the IFRAME have completed loading. This event provides a location to include script that executes as soon as the contents of the IFRAME have completed loading.

Note

This event never occurs in Microsoft Dynamics CRM for tablets because IFRAMEs aren’t displayed.

More information: IFRAME OnReadyStateComplete Event

PreSearch event

Use the addPreSearch method to add an event handler to a control for a lookup attribute. There is no user interface to add an event handler manually. Use this event with the addCustomFilter, addCustomView, and setDefaultView methods to control the views opened when people search for a record to set as the value of a lookup field.

More information: Lookup Control PreSearch Event

See Also

Write code for Microsoft Dynamics CRM 2013 forms
Use the Xrm.Page object model
Form scripting quick reference
Use JavaScript with Microsoft Dynamics CRM 2013
Client-side programming reference
Form events (client-side reference)
<events> (FormXml)