Batch Type Add-In Overview

Version: This material pertains to version 3.0 of Blackbaud CRM SDK.

The BatchTypeAddInSpec is used to add custom Webshell Event Handlers to an out-of-the-box batch type. Batch event handlers are used to enhance data validation from the Web Shell batch UI grid and can be bypassed via 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. Web Shell event handlers can be used to inject event handler behavior into a batch that ships with Blackbaud CRM. For example, a Batch Type Add-in can be used to register a Web Shell event handler that adds custom buttons, button groups, and regions (tabs). You can also display custom prompts during data entry, validate fields and provide messages, retrieve default data when a field changes, clear fields, make a field be unavailable for editing, and show custom dialog screens.

Add a Batch Type Add-In to a UI Model Project

The SDK ships with an item template that you can use from within your UIModel project to create a Batch Type Add-in.

Figure: Add a Batch Type Add-in

Next , you are prompted for the batch type to register the add-In for:

Figure: Select the batch type

The template will then generate a very simple XML spec document, which you can immediately load using LoadSpec.

Figure: The spec and add-in class file are generated for you, how nice!

After the spec is loaded, the add-in will appear within the Batch Type metadata feature page. From here, the add-in can be enabled and disabled.

Figure: The batch feature page has an AddIns section. This is reminiscent of the data form feature page. Data forms can have add-ins too.

In addition, the template generates the Add-In class. We can add code to this class to respond to batch entry events as they occur within the Web Shell batch user interface.

Figure: The generated Add-In class.

Add Behavior to an Out-of-the-box Batch Type

Let's inject some behavior by defaulting the country to "Australia" if the Address type is equal to "Business." For more details on the event handlers, field-changed handlers, and methods in this sample, use the bit.ly URLs in the code comments to view the associated Web Shell batch event handler reference documentation. Here is the commented code for the class:

Imports Blackbaud.AppFx.BatchUI

Public NotInheritable Class ConstituentBatchBatchEntryHandler
	Inherits Blackbaud.AppFx.BatchUI.BatchEntryHandler   

    'Let's establish a FieldChangedHandler for the Address type code column in the batch ui.
    'If the user selected "Business" from the Address Type drop down list within the batch ui grid
    ' then default the Country field to 'Australia'

    ' The AfterLoad event fires after the event handler is loaded.  This event is commonly 
    ' used to define business rules on the fields within the Webshell user interface grid.  
    ' For example, FieldChangedHandlers can be added to respond to a change to a field.
    ' (Docs: http://bit.ly/ZILk87)
    Private Sub ConstituentBatchBatchEntryHandler_AfterLoad(sender As Object, e As System.EventArgs) Handles Me.AfterLoad

        'Not all batches, which are created from a batch template, 
        ' will contain every field defined within the batch type. 
        ' Therefore, the developer can use FieldIsDefined to check and 
        ' see if the field exists within the batch prior to coding something 
        ' that depends on the field’s existence. (Docs:  http://bit.ly/11WbDeF)
        If FieldIsDefined("ADDRESS_ADDRESSTYPECODEID") Then

            'FieldChangedHandlers has an Add procedure which is used to add a FieldEventHandler 
            ' for a particular field within the batch grid user interface.  
            ' When the assigned field changes, the AddressOf operator is used to 
            ' designate a delegate to handle the event. (Docs: http://bit.ly/ZIKEPP)
            Me.FieldChangedHandlers.Add("ADDRESS_ADDRESSTYPECODEID", AddressOf DefaultBusinessAddressDetails)
        End If

    End Sub

    'Here is the delegate to handle the event.
    Private Sub DefaultBusinessAddressDetails(ByVal e As FieldEventArgBase)

        'Grab the value from the ADDRESS_ADDRESSTYPECODEID field via e.Field.Name
        Dim ID = DirectCast(GetValueTranslationFromFieldID(e.Model, e.Field.Name, ""), String)

        If ID.Equals(String.Empty) Then Return

        'If the user selected "Business" from the Address Type drop down list within the batch ui grid
        ' then default the Country field to 'Australia' by using the appropriate primary key/ID column
        ' value from the Country table. 
        If ID = "Business" Then
            If Me.FieldIsDefined("ADDRESS_COUNTRYID") Then
                TrySetValueForFieldID(e.Model, "ADDRESS_COUNTRYID", "F189F24C-2538-46A1-8458-1E3F3967B843")
            End If
        End If
    End Sub
End Class

The Results

After the code is compiled and deployed to the appropriate bbappfx\vroot\bin\custom folder, and the appropriate application pool is recycled, we can view the results within the Web Shell batch user interface. When the user selects the "Business" address type....

Figure: An address type of "Business" causes the country to default to "Australia."

... the Country defaults to "Australia."

Figure: And here is the customized default value behavior for the Country field within the out-of-the-box Constituent Batch type.