Share via

Use form and field events

  • Article

 

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

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: 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 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.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 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. 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.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 fireOnChangemethod 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:

  • Perform calculations to change other fields based on changing values.

  • Change the formatting of fields, such as telephone numbers.

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 365 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.

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

Business Process Flow control events

Microsoft Dynamics 365 (online & on-premises) provides three events for user interaction with the business process flow control.

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.

Each of these methods accept a function as a parameter to add or remove from the event handler. More information: Methods to manage event handlers.

See Also

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

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright