Version: This material pertains to version 3.0 of Blackbaud CRM SDK.
New IsCancelable Attribute for Generic UI Actions
Within a data form's FormMetaData section, a new IsCancelable attribute is now available within the UIAction element. The term "data form" refers to a traditional data form such as an Add Data Form or a Custom UI Model. Use of the attribute only applies to a UIAction that is generic meaning the UIAction does not contain child elements such as ShowAddForm or ShowDataForm. When UI Model code is generated from the data form, the generic UIAction allows the developer to code an event handler for the UIAction. The UIAction can render as a button or link on the data form. This provides a mechanism to run code on the server side, such as making a call to a data list to retrieve some rows of data.
Figure: The IsCancelable UIAction attribute is only applicable to generic UIActions.
Setting the IsCancelable=True attribute to your generic UIAction and generating your UI Model for the data form (or custom UI model) makes it possible to access the .CancelID property on the UIModeling.Core.InvokeActionEventArgs that is passed into the InvokeAction event handler for that UIAction. If the work you perform within your UI model's action event handler involves utilizing the AppFx service method that implements ICancelAsync, you will be able to pass the .CancelID property to the web service request which knows how to be canceled.
Figure: Event Handler for the UIAction
Note: As of SDK 3.0, only DataListLoad and CodeTableEntryDelete implement ICancelAsync and therefore are the only service methods that honor the .CancelID property. In addition, for DataListLoad, only stored procedure based data lists can be canceled.
Here is the data form containing the generic UI action. When the "Start" UI action is selected by the user, an InvokeAction event is raised. Our UI Model code contains an event handler. Code within the event handler runs a long-running DataListLoad service method/operation.
Figure: The generic UI Action. When clicked, the UI Model event handler is called upon to handle the ActionInvoked event.
Because IsCancelable is True, a cancel button appears on the Loading dialog screen after the action is invoked.
Figure: The user selects cancel.
If the service operation is canceled, the call from the service method (such as DataListLoad) returns normally. In our event handler, we can inspect the reply's DataListLoadWasCancelled property to see if the operation was canceled. If so, we can adjust the user interface accordingly.
Figure: We can inspect the reply to see if the operation was canceled.
Figure: Notify the user the operation was canceled
Tip: You can find a code sample to demonstrate a generic UI action with an IsCancelable attribute in the GenericUIActionIsCancellable.Custom.xml Custom UI Model spec in the SPDataList.Catalog Visual Basic project. You can find a code sample to demonstrate a call to a long-running stored procedure-based data list from a generic UI Action event handler in the GenericUIActionIsCancelableUIModel.vb UI model class in the Visual Basic project named IsCancelable.UIModel. The code sample can be found here.