NextGen Consulting

Implementing Lookup Control

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
• Lookup & Details
• Details
• Clear

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.

 

 

LookedUp Property

 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:

 LookUpContact.setLookedUp(true);

  

 

Lookup Control Flow

 

 

 …

Implementing Lookup Control 

The following step by step example illustrates how to use the Lookup control.

Goal:

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.

 

Steps

 

A.   Add Controls on form’s panel.

We first add the following controls:

• Lookup Button     name: “LookUpContact”
• TextBox               name: “txtContactName”
• Label                   name: “lblContactName”

 

Lookup Control:

 

 

B.   Add data Models:

• contactDM
• contactSearchInfoDM
• contactSearchCriteriaTDM

    

contactDM properties:

 

 

 

contactDM Data Model Definition

 

   

 

contactSearchInfoDM Data Model Definition

  

  

 

contactSearchCriteriaTDM Data Model Definition

  

  

 

C.      Add Search Launch Action:

Name: “contactLookupAction”

 

 

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:

 

    

 

DCE_ContactLookup Properties

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.

 

DCE_ContactLookup Events

 

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

SourceDMPath:    $DataProvider:gridListing:SelectedRowsTDM

  

 

  

DCE_ContactLookup Item field #1 properties

  

   

 

DCE_ContactLookup Item field #2 properties:

   

   

Test it – Run the application

 

Step 1:

• The user enters first two letters of contact’s name.
   
• The User clicks the Lookup button
    
  
   
• 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.
   

 

  

 

Step 2:

• 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’.