Overview

When you save data from the batch UI grid to the batch table, it can cause exceptions from the database, form field metadata, and RAISERROR () from the save implementation. In this section, we review how you can enrich the batch UI grid experience and data validation capabilities of your batches through the use of batch handlers.

Web Shell Impact to Event Handlers

Older batch types designed to run within the ClickOnce Smart Client will require that the event handler code and custom dialog screens be rewritten to be Web Shell-compliant. The legacy ClickOnce batch implementation is tied to Windows UI components like the Browser.Controls.EditGrid. This reliance on Windows controls means that the event handlers and custom dialog screens of a specific batch type are not portable to different presentation layers, such as the new Web Shell. Older batch types built upon the ClickOnce, Windows-based shell use WinForm technology for the custom dialog screens. These will not work in the newer Web Shell user interface that requires that a UI Model based Custom UI Model data form to present a custom dialog screen. Older batch types designed to run within the ClickOnce Smart Client will require that the event handler code and custom dialog screens be rewritten to be Web Shell-compliant.

Web Shell Event Handlers Live in the UIModel Project

Web Shell event handlers live in the UIModel project (ex: Blackbaud.CustomFx.FoodBank.UIModel), while any ClickOnce event handlers remain within the Windows-based Client project (ex: Blackbaud.CustomFx.FoodBank.Client).

Existing ClickOnce event handlers should remain in the Client project to support the batch when it is run within the ClickOnce Smart Client. Existing ClickOnce event handlers will need to be copied to a UIModel project and converted to run within Web Shell.

Keep ClickOnce Event Handlers

Existing ClickOnce custom dialog screen/forms should remain in the Client project to support the batch when it is run within the ClickOnce Smart Client. Existing ClickOnce custom dialog screen/forms need to be converted to a UI Model equivalent such as aCustom UI Model form.

Within the BatchTypeSpec, ClickOnce-based event handlers are referenced within the EventHandlers tag. Web Shell-based event handlers are referenced within the WebEventHandlers tag. ClickOnce event handlers should remain in the Client project to support the batch when it is run within the ClickOnce Smart Client.

Web Shell Event Handlers Inherit from Different Base Class

ClickOnce-based event handlers inherit from Blackbaud.AppFx.Browser.Batch.BatchEntryHandler class, while Web Shell-based event handlers inherit from Blackbaud.AppFx.BatchUI.BatchEntryHandler class.

Don't Depend on Batch Event Handlers to Check Your Data in Every Scenario

Let's get a few things straight before we get into the detail.

• Batch event handlers only get fired through the batch user interface grid.

• Batch event handlers (and the batch UI) are bypassed with batch import (shown below) and the Infinity Web API (not shown below).

• Starting with 2.94, Batch Import Handlers allow the SDK developer to validate, alter, scrub, and enhance each row of data just before it is added (imported) into the batch staging table.

Batch event handlers are used to enhance data validation from the batch UI grid and can be bypassed through Import. Therefore it is safe to assume that to ensure proper data validation, you cannot depend on batch event handlers as your primary mechanism for data integrity. Instead, emphasis should be placed in the following:

• Form field metadata within the Add Batch Row Data Form and Edit Batch Row Data Form

• Batch import handler logic

• Save implementation logic within the Add Batch Row Data Form and Edit Batch Row Data Form

• Table constraints with the batch staging table(s)

• Validation logic within the save implementation of the Commit Data Form

• Commit logic within the save implementation of the Commit Data Form

• Table constraints with the production staging table