Share via

Use form and field events

  • Article

 

Applies To: Dynamics CRM 2015

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. Handlers for the PreSearch event and events raised by the business process flow control can only be added and removed using methods for the respective 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

Business Process Flow control events

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: d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnLoadEvent

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 button 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. fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_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. ab100e06-a3ba-47f8-a8f8-7b5fab2ab66d#BKMK_dataSave method and there is unsaved data in the form.

  • Code executes the Xrm.Page.data. ab100e06-a3ba-47f8-a8f8-7b5fab2ab66d#BKMK_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 bf64f471-7582-45e7-b8ed-370bfbecda68#BKMK_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: d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnSaveEvent

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. For these controls the event occurs immediately.

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.6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_fireOnChange method will also cause this event to occur.

The OnChange event doesn’t occur if the field is changed programmatically using the 6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_setValue method. If you want event handlers for the OnChange event to run after you set the value, you must use the 6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_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: d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_FieldOnChangeEvent

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: d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_TabTabStateChangeEvent

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: d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_IFRAMEOnReadyStateCompleteEvent

PreSearch event

Use the 51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_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 51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_addCustomFilter, 51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_addCustomView, and 51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setDefaultView methods to control the views opened when people search for a record to set as the value of a lookup field.

More information: d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_LookupPreSearch

Business Process Flow control events

Microsoft Dynamics CRM 2015 and Microsoft Dynamics CRM Online 2015 Update provides two events for user interaction with the business process flow control.

  • OnStageChange
    Occurs when a stage changes. More information: d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnStageChange.

  • OnStageSelected
    Occurs when a stage is selected. More information: d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnStageSelected.

There is no UI to register scripts for these events. Use the following methods in functions registered in the form OnLoad event to register your functions for these events.

  • Xrm.Page.data.process.6b79eb8c-8293-4d3a-a3a7-ea35157cde37#BKMK_addOnStageChange

  • Xrm.Page.data.process.6b79eb8c-8293-4d3a-a3a7-ea35157cde37#BKMK_addOnStageSelected

  • Xrm.Page.data.process.6b79eb8c-8293-4d3a-a3a7-ea35157cde37#BKMK_removeOnStageChange

  • Xrm.Page.data.process.6b79eb8c-8293-4d3a-a3a7-ea35157cde37#BKMK_removeOnStageSelected

Each of these methods accept a function as a parameter to add or remove from the event handler. More information: 6b79eb8c-8293-4d3a-a3a7-ea35157cde37#BKMK_EventHandlerManagement.

See Also

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

© 2016 Microsoft. All rights reserved. Copyright