Form events (client-side reference)

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

All client-side code is initiated by events. In Microsoft Dynamics 365, you will associate a specific function in 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

OnProcessStatusChange event

OnStageChange event

OnStageSelected event

Knowledge base search control events

Read-Only Subgrid OnLoad event

Editable grid events

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 365 for tablets client is disconnected, the OnLoad event is the only event that will occur.

OnSave event

The OnSave event occurs when:

• The user clicks the 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 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.

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.

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.

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.

Lookup Control PreSearch event

The lookup control has a PreSearch event that occurs just before the control launches a dialog to search for records. There is no 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.

OnProcessStatusChange event

This event occurs when the status of a process instance changes. Use the Xrm.Page.data.process.addOnProcessStatusChange method to add event handlers for this event and the Xrm.Page.data.process.removeOnProcessStatusChange method to remove them. More information: Write scripts for business process flows.

OnStageChange event

This event occurs when the stage of a business process flow control changes. This event occurs when the user clicks the Next Stage or Move to previous stage buttons in the user interface or when a developer uses the Xrm.Page.data.process.moveNext or Xrm.Page.data.process.movePrevious methods. You can’t cancel the stage change using code in a handler for this event.

An execution context object is passed to event handlers for this event. You can use the getEventArgs function to retrieve an object that has the following methods:

• getDirection
  Returns a string that is either “next” or “previous” to show the direction of the stage change.

• getStage
  Returns a stage object. Except when the navigation moves to a new entity, the stage returned represents the destination stage object,that is, the next active stage. When the navigation moves to a new entity, the stage is the stage being navigated from, that is, the previous active stage object. More information: Stage methods.

Use the Xrm.Page.data.process.addOnStageChange method to add event handlers for this event and the Xrm.Page.data.process.removeOnStageChange method to remove them. More information: Write scripts for business process flows.

OnStageSelected event

This event occurs when a stage of a business process flow control is selected. You can’t cancel the stage selection using code in a handler for this event.

An execution context object is passed to event handlers for this event. You can use the getEventArgs function to retrieve an object that has the following methods:

• getStage
  Returns a stage object representing the selected stage. More information: Stage methods.

Use the Xrm.Page.data.process.addOnStageSelected method to add event handlers for this event and the Xrm.Page.data.process.removeOnStageSelected method to remove them. More information: Write scripts for business process flows.

Knowledge base search control events

The knowledge base search control can only be added to forms for organizations that has the knowledge management feature enabled. This control has two events (OnResultOpened and OnSelection) that developers can programmatically assign event handlers to. More information: Knowledge base search control (client-side reference)

Read-Only Subgrid OnLoad event

Attach event handlers to the OnLoad event of subgrids. More information: Write scripts for subgrids

Editable grid events

Attach event handlers to the editable grid events. More information: Editable grid objects and methods (client-side reference)

See Also

Form scripting quick reference
Write code for Microsoft Dynamics 365 forms
Use the Xrm.Page object model
Client-side programming reference
Write scripts for business process flows

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright