About Lookup Control
The Lookup control assists users search for data with which they need to associate.
For example, when creating a new contact, we need to need to associate it with a site to which this contact belongs.
The lookup button launches a search form which allows the user to select the relevant record that update the necessary values in the launching form.
The lookup button is often used in create and edit forms, where the main focus object (in our above example – a new contact) needs to be related to another object (site in above example.
The Lookup control allows users to search and associate objects in the application. The control provides standard drop-down button functionality plus additional specific ones.
The Lookup control contains the following predefined menu items:
- Lookup & Details
The Lookup menu item should be associated with SearchLaunchAction. The Launch action should have a Data Communication Element that returns data from a listing form when ‘postSelectionCommit’ event is fired by the Grid control on the launched form.
The Lookup Control is set to lookedUp if the data models targeted by the DCE are updated after lookup.
- The lookedUp property status is visually reflected by a green checkmark icon displayed over the lookup glasses.
- The lookedUp property can be set programmatically using the following code:
Lookup Control Flow
Implementing Lookup Control
The following step by step example illustrates how to use the Lookup control.
Our goal is to allow the user to enter in the textbox part of the contact’s first name.
- Upon clicking on the Lookup Button, Its corresponding Search Launch Action will invoke the Search Contact form and set its search criteria to look for a contact whose first name starts with the entered string.
- If the Search Contact form finds a single record, the Search Contact form will remain invisible and immediately return back to the Lookup form while passing selected fields of the found contact record using CDE (Communication Data Elements).
- If more than a single record is found, the Search Contact Form will be opened displaying a list of records which address the query. The user can then manually select any of the displayed records and click the Grids ‘Select’ button to pass the information back to the calling form.
- The data returned to the calling form (the one which contains the LookUp button) should contain the found contact’s first and last names (first_name, last_Name).
- The returned data for first_name and last_name will be formatted to construct a single field which contains the user full name. This field (‘formatted_name”) is part of the contactDM Data Model and is bound to the textbox “txtContactName”.
- When updated with the full name, the contatDM field will be immediately rendered by the textbox.
A. Add Controls on form’s panel.
We first add the following controls:
- Lookup Button name: “LookUpContact”
- TextBox name: “txtContactName”
- Label name: “lblContactName”
B. Add data Models:
contactDM Data Model Definition
contactSearchInfoDM Data Model Definition
contactSearchCriteriaTDM Data Model Definition
C. Add Search Launch Action:
Set Search Launch Action properties
Search Launch Action Launch Data Map
Search Launch Action LogicalFormName: com.amdocs.crm.isupport.contact.ContactList
Search Launch Action Events
The contactLookup_ActionStart event prepares the search criteria data
D. Add DCE_ContactLookup Data Communication Element:
The triggerEvent sets the name of the event that triggers this DCE.
If the triggerSource property is not set, then this is considered as a user event which needs to be fired by the application code by calling DataCommSet.triggerEvent.
The DCE_ContactLookup_postExecuteInTarget event handler copies first_name and last_name fields values back to contactDM ‘formatted_name’ field value. The ‘formatted_name’ value is bound to the textbox ‘text’ property. This field will be populated with first and last names.
DCE_ContactLookup Item Properties
DCE_ContactLookup Item field #1 properties
DCE_ContactLookup Item field #2 properties:
Test it – Run the application
The user enters first two letters of contact’s name.
The Search Launch action launches the Search Contacts form and passes it the search criteria data model (first_name startsWith ‘yu’).
The Search Contact form silently searches for contact’s first name that starts with ‘yu’ and find a single record that match these criteria.
Records first and last names are passed back to the calling form by Data Communication Elements.
The calling form pass first_name and last_name to the contactDM field named formatted_name.
The formatted_name is bound to the Contact Name textbox. Full name displayed.
The LookedUp propery is set to ‘validated’.