Share via

Form events (client-side reference)

  • Article

 

Applies To: Dynamics CRM 2015

All client-side code is initiated by events. In Microsoft Dynamics CRM, 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

OnStageChange event

OnStageSelected event

Parature knowledge base search control events

Subgrid OnLoad 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 don’t 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 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 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. In these cases 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 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. 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.

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.

Parature knowledge base search control events

Microsoft Dynamics CRM Online 2015 Update 1 introduced a new knowledge base search control that can only be added to forms for organizations that are integrated with Parature. This control has two events (OnResultOpened and OnSelection) that developers can programmatically assign event handlers to. More information: Parature knowledge base search control (client-side reference)

Subgrid OnLoad event

With CRM Online 2015 Update 1 you can attach event handlers to the OnLoad event of subgrids. More information: Write scripts for subgrids

See Also

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

© 2016 Microsoft. All rights reserved. Copyright