Using the SmartBusinessEntityLookup Control

The SmartBusinessEntityLookup Control can be used to support the end user when entering data that has foreign key fields. It provides functionality to search for information on the backend (database) and provides a separate, standarized Form with filtering and sorting possibilities. The population of other related fields like e.g. when looking up the SalesRep short tag “BBB” retrieve and display the full name “Bubba B. Brown” is also supported.

Setting up a SmartBusinessEntityLookup on a Viewer

It is a common requirement when entering data in a SmartViewerControl to select a value from a large list of options (e. g. the SalesRep, Item, Customer). Compared to a combo box which is meant to be used for small option sets (typically not more than 15 entries) the Lookup control has additional capabilities and is suited for infinite lists of records. You can define multiple filters used to find the entry you are looking for and reuse the same Lookup wherever you need the same information.

The following section will show a step by step description on how to add and configure a SalesRep Lookup to a customer viewer control. The sample starts with having a Form (CustomerForm) and a Viewer (CustomerDetailViewerControl) ready to be used.

Add a SmartBusinessEntityLookup Control to a Viewer

First thing to get a SmartBusinessEntityLookup added to the CustomerDetailViewerControl is to open the viewer control and add the control from the toolbox by double clicking it or select it from the toolbox and place it with the mouse wherever it should be.

The added SmartBusinessEntityLookup instance smartBusinessEntityLookup1 should replace a possibly already existing simple field for the SalesRep column on the viewer control. Shown below is the viewer with the SalesRep Lookup and the full name field of the SalesRep on the right side.

By selecting the Designer Verb AddLookupButton from either the Control instance’s context menu or the hyper links at the bottom of the property grid the Lookup button will be added to the Lookup (the button is shown at the right hand side within the Lookup).

Select the SalesRepBusinessEntity and the tables to be used by the Lookup

The next required step is to configure the BusinessEntity and Table that should be used by the Lookup for selecting records from. There are Designer Verbs to accomplish this by selecting “Select Business Entity” and “Select Tables” in this sequence. In this example I am using a SalesRepBusinessEntity including a table called eSalesRep.

Configure the SmartBusinessEntityLookup using the Designer

The SmartComponent Library provides the SmartBusinessEntityLookup Desginer designed to make the configuration of the Lookup as easy as possible. The Lookup Designer is accessible as well from a Designer Verb.

The tool is separated in two different areas. On the left side you can define all settings concerning the Lookup instance in the SmartViewerControl.

On the right side you define the options for the Lookup Dialog, particularly the Lookup Browser and the filter options. The Lookup Dialog will open, when the user presses the Lookup Button of the Lookup Control.


For the Lookup Control itself we are specifying the following settings on the left side:

Lookup

Values

Description

Lookup Keys



Key   Field

SalesRep

The Key Field defines the column from the lookup table (eSalesRep in this sample) who’s value will be assigned to the Lookup Control itself (the Value property) when the user selects a record by   entering a (partial) key in the Lookup Control itself or selects a record from the Lookup Dialog.

Key   Value Column

SalesRep

The Key Value Column defines the column from the lookup table (eSalesRep in this sample) whose value will be assigned to the LookupKeyValue property of the Lookup Control when the user selects a record by entering a (partial) key in the Lookup Control itself or selects a record from the Lookup Dialog. The LookupKeyValue property and thus the Key Value Column is required when using non-meaningful keys in your database design and/or Business Entity design.

Mapping


Field/Control   mapping allows the Lookup Control to assign values (Text property) to additional Controls in the Viewer. This is useful to return additional fields values (like the RepName) from the Lookup whenever the user selects a record. The mapped fields are maintained in a browser using two combo-box columns. The SmartBusinessEntityLookup allows developers to use any number of mapped fields/controls

Mapped   Field

RepName

The Mapped Fields   define the fields from the Lookup’s Business Entity that will be used to   assign values to the mapped controls.

Mapped   Control

CustomerBindingSource

_eCustomer_RepName

The Mapped Controls   are the controls receiving the values from the Lookup Business Entity.

Lookup Query   String

FOR   EACH SalesRep WHERE eSalesRep BEGINS "&1".

The Lookup Query String defines the query used to search for values in the Lookups Business Entity when the user either leaves the Lookup Control or does not type any keys for 0.75 seconds. The current value of the Lookup Control (potentially a partial key) is inserted to the query string at the location of the &1 token. The token should be put in quotes no matter of the data-type of the key field.


And on the right side I use these settings:

Lookup Dialog

Values

Description

Title

SalesRep Lookup

The title for the lookup dialog, like “Lookup SalesRep”

Filter


Filters can be used by the user to search records in tables with a lot of records. The Lookup dialog supports any number of filters you need (including zero and one). To keep things simple for the user, a filter is always applied to a single field only.