Step by Step: Create a Batch Action to Display a Custom UI Model

Custom UI Models are created by generating a UI Model from a CustomUIModelMetadata spec. In the previous section, we created a CustomUIModelMetadata spec, copied a form field collection from the batch add form to the CustomUIModelMetadata spec, and then generated a UI Model for the CustomUIModelMetadata spec. After we create a Custom UI Model dialog screen, we can open that dialog from the batch grid window via an action button.

Figure: Open a dialog screen (Custom UI Model) from an action within the batch

The UIModel project should include a class that inherits from Blackbaud.AppFx.BatchUI.BatchEntryHandler. This class represents the batch handler which is also commonly referred to as the batch event handler or event handler. Within this class, the software developer can add event handlers and thereby provide additional functionality to the batch.

The the batch will raise the DefineActions event so your handler code can add actions (buttons) to the batch. When the actions are invoked (clicked), the ActionInvoked event is raised. You can handle the ActionInvoked event and provide data from the batch row to the Custom UI Model dialog screen.

Actions are organized on the ribbon toolbar by creating regions and groups. This example demonstrates how to use the DefineActions event to add an action to an action group.

The sample below demonstrates the creation of a BatchShowCustomFormAction that will launch our Custom UI Model data form. The Custom UI Model data form is referenced by its class name (FBTXBatchFoodItemsCustomUIModel) within the UIModel assembly (Blackbaud.CustomFx.FoodBank.UIModel.dll). The action is organized within an action group within an action region and is displayed within the ribbon at the top of the batch grid data entry screen.

Step 1 -  Open the batch handler class file within your UIModel project.

Step 2 -  Add the following constants and memory variable to the batch handler class.

We will use these when we programmatically create a batch action (button) for the batch to launch the Food Items dialog screen (Custom UI Model).

'Food Items Child Custom UI Model Dialog Screen constants and memvar

Private Const FBTXBATCHFOODITEMS_ASSEMBLYNAME As String = "Blackbaud.CustomFx.FoodBank.UIModel.dll"

Private Const FBTXBATCHFOODITEMS_CLASSNAME As String = "Blackbaud.CustomFx.FoodBank.UIModel.FBTXBatchFoodItemsCustomUIModel"

Private Const FBTXBATCHFOODITEMS_BUTTONKEY As String = "FBTXBATCHFOODITEMSBUTTONKEY"

Private Const FBTXBATCHFOODITEMS_IMAGEKEY As String = "RES:reportspec"

Private _FBTXBatchFoodItemsAction As BatchShowCustomFormAction = Nothing

Step 3 -  Create an event handler for the DefineActions event.

The DefineActions event is raised so handlers can add actions to the batch. When the actions are invoked, the ActionInvoked event is raised. Actions can be organized on the ribbon toolbar by creating regions and groups.

Add the code below to your batch handler class:

Private Sub FoodBankTransactionAddBatchHandler_DefineActions(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.DefineActions

	If Me.Actions.Count = 0 Then

		Dim actionregion As New BatchActionRegion("FBTX_REGION", "Tx Region") With {.ShortKey = "K"}

		Dim actiongroup = New BatchActionGroup("FBTX_GRP", "Transactions")

		actiongroup.Add(FBTXBatchFoodItemsAction)

		actionregion.Add(actiongroup)

		Me.Actions.Add(actionregion)

	End If

End Sub

Step 4 -  Create a property to return the batch action.

Create a private read-only property to return an object of type BatchShowCustomFormAction which represents the batch action. The batch action is what actually opens the Custom UI Model dialog screen for the food items. Looking back at the previous step, our DefineActions event handler calls upon this property to add the action to the action group. As part of creating the action, we will provide the constant for the button key, image key, assembly name, and class name. We will provide a field value condition object as the action's enabled rule. The rule is defined as "Enable the action whenever a value exists for the Food Bank (PRIMARYCONTEXTRECORDID) field."

Private ReadOnly Property FBTXBatchFoodItemsAction() As BatchShowCustomFormAction

	Get

		If _FBTXBatchFoodItemsAction Is Nothing Then

			_FBTXBatchFoodItemsAction = New BatchShowCustomFormAction(FBTXBATCHFOODITEMS_BUTTONKEY, "Food Items",

			FBTXBATCHFOODITEMS_IMAGEKEY, FBTXBATCHFOODITEMS_ASSEMBLYNAME, FBTXBATCHFOODITEMS_CLASSNAME)

			'If the food bank (PRIMARYCONTEXTRECORDID) column has a value then enable the action button.

			_FBTXBatchFoodItemsAction.EnabledRule = FieldHasValue("PRIMARYCONTEXTRECORDID")

			_FBTXBatchFoodItemsAction.ShortKey = "F"

		End If

		Return _FBTXBatchFoodItemsAction

	End Get

End Property

At this point, we have an action that opens a Custom UI model dialog screen. Next we will programmatically pass data from the batch grid to the dialog screen and vice versa.