Example: Web Shell Batch Event Handler

Overview

This sample serves as demonstration of how to code batch handlers for Web Shell and display custom dialog windows with a Custom UI Model. This sample is designed to work in Web Shell only. This sample batch is based on the food bank customization and allows users to enter food bank transactions (USR_FOODBANKTXHEADER table) and related transaction details (USR_FOODBANKTXDETAIL table). A food bank transaction record is the parent record and the transaction detail records are the children records. The transaction detail records contain reference to food items (USR_FOODITEM).

Figure: Data model for the food bank customization

This sample attempts to highlight many common scenarios you will encounter when you build a batch for the Web Shell including:

• Manage children records within the batch with either the default user entry grid or a dialog screen.

• Use event handler code to retrieve and set data to and from the user interface grid.

• Programmatically call upon a data form to retrieve field value defaults within the batch entry grid.

• Create dialog screens with a Custom UI Model.

• Create actions within action groups to launch dialog screens.

• Implement business rules and validate data entry within the batch by:

  • Enabling or disabling fields within the user interface grid..

  • Dynamically defaulting data when a field changes within the user interface grid.

  • Clearing field values when a field changes within the user interface grid.

• Use field and row annotations to display messages within the user interface grid.

• Handle common batch entry handler events such as AfterLoad, DefineFieldRules, DefineActions, ActionInvoked, and SearchComplete.

• Use the RowContextWindowtag within the BatchTypeSpec to:

  • Display summary information for the current row context below the user interface grid using a view data form.

  • Edit the current row context record via an edit data form.

  • Display a page for the current row context record.

Add Food Bank Transaction Records

When you commit the batch, the Food Bank Transaction Add Batch populates rows into the food bank transaction header and detail tables. The transaction header is populated by selecting a food bank (organization) record followed by selecting the constituent related to the transaction along with the transaction date and receipt printed flag.

Figure: Add food bank transaction header records

Manage Child Records

The transaction detail consists of adding references of food item child records to the transaction header. Transaction detail is added by selecting the Food Items column drop-down list box to reveal the standard batch entry user interface child grid. When a food item is selected within the child grid, the amount value will be retrieved from the database and the quantity column value will be defaulted to a value of 1.

Figure: Add the food item child transaction detail records

Prerequisites

This content assumes you have experience with the food bank customization, Batch and the concepts surrounding Batch Event Handlers.

This example assumes you have the batch type named "Food Bank Transaction Add Batch" loaded into the catalog system. You will need to ensure you have loaded the catalog items (specs) referenced by the FoodBankTransactionAddBatch.Package.xml PackageSpec into the catalog system prior to adding a batch event handler for this batch type.

The "Sample Code Location" section below describes the location of the specs supporting this batch type.

Sample Code Location

Note: You can find the code for this example within the food bank source code. Download the source code here.

Within the catalog project's Food Bank TX Adv Add folder, you will find the specs to support the batch type and custom dialog screens.

Figure: Catalog items to create the batch type and support the data retrieval for the Custom UI Models dialog screens

Within the UIModel project, you will find the Web Shell batch event handler class file and Custom UI Models to support the custom dialog screens.

Figure: The UIModel project holds the event handler code and Custom UI Models which support the custom dialog screens

Next Step: Adding the Batch Handler to the UI Model Project