How To: Add Lookup Information to a Form

Use the Lookup control to select a value from a dialog window containing a list of values. For example, you may have a SmartObject that contains a list of items. As part of your form you want to show a subview with the list of items (lookup information), and then select an item to populate data on the form.

Runtime example of the Region lookup list

Try it yourself!

Scenario

Your organization uses a form to capture customer information. To make it easier to complete the form, you want to show a dialog box so that the form user can search and select a region for the new customer.

Steps

For this scenario, you begin by building two SmartObjects called Customer and Region that stores customer and region details. Next, you use the Customer SmartObject to create an item view and from the Region SmartObject generate a list view. You use the item view to capture the data on the form and the list view as the lookup reference. You edit the Customer item view and change the Region ID text box to a lookup control. You then configure the Region ID field to use the Region SmartObject as the data source for the lookup list. You add a rule to the Customer item view to open the Region list view in a subview, and add another rule to populate the Region ID field with the selected item when you double click it. Finally, you add some data to the Region SmartObject and test the solution.

Prior to working through this how-to, you should know how to work with the category system and add elements such as SmartObjects and views. If you do not know how to build the basic application elements, see: Getting Started (with the Designer).

Setup Steps

The following steps set up the scenario from start to finish. If you want to skip the setup steps and view the topic step, go to Edit and configure the Region ID field.

Create two new SmartObjects called Customer and Region.
1. From the the Designer, create the Customer SmartObject as shown below.
2. Create the Region SmartObject as shown below.
Generate two views, an Item view from the Customer SmartObject and a List view from the Region SmartObject.
1. From the Designer, right click the Customer SmartObject, select Generate Views and check the Item check box to generate the Customer Item view. Click OK.
2. To generate the second view, right click the Region SmartObject, select Generate Views and check the List check box to generate the Region List view. Click OK.

Edit and configure the Region ID field

In this section, you edit the Customer Item view, change the Region ID text box to a lookup control, and specify the Region SmartObject as the data source. On the Customer Item view, add two rules: One rule to open the Region list view in a subview when you click the Region lookup and another rule to transfer data to the Region ID when you double click an item on the Region List subview.

Change the Region field to use a lookup control and edit the control's properties
1. From the the Designer, locate the Customer Item view and select Edit.
2. Select the Region ID field and click the Change Control icon.
3. Select Lookup and click OK.
4. You changed the Region ID field from a text box to a lookup field.
5. Next you configure the data source for the lookup field. Select the Region ID field, then click the ellipsis next to the SmartObject view property.
6. Click the ellipsis next to SmartObject, browse to and select the Region SmartObject. The Method, Value and Display is populated as shown below. Click OK.
7. Still on the Customer Item view, select the Rules tab and click Add Rule.
8. In the search field type when a control, locate the Control Events section, and click When a control on the View raises an event.
9. Select RegionID Lookup for the control and Clicked for the event.
10. From the Actions tab, type open a in the search field, locate the Subview Interaction section, and click Open a subview.
11. Select the Region List view. This rule opens the Region List view in a subview when you click the RegionID Lookup control. Click OK.
12. Note how the Region List subview executed Initialize rule is automatically added. This rule populates the Region List subview.
13. Click Add Rule again. Type When a subview executes, locate the Subview Events section, and click When a subview executes a method.
14. Select the List Item double click option.
15. From the Actions tab, type transfer , locate the Data Transfer section, and click Transfer data.
16. Click configure, then expand the Region SmartObject in the Context Browser. Drag the RegionID property into the RegionID Lookup field. Click OK.
17. Still in the Actions tab, type close, locate the Subview Interaction section, and select Close a subview or subform. This rule transfers data from the Region List subview to the Customer View when an item is double clicked on the subview, and then the Region List subview closes. Click OK to save the rule.
18. The Customer Item view rules should look like the image below. Click Finish to save and exit the view.
Generate an editable list view, add data to the Region SmartObject, and generate the Customer form.
1. From the Designer, right click the Region SmartObject, select Generate Views and check the Editable List check box to generate the Region Editable List view. Click OK.
2. Select the view and click Run.
3. Add data to the Region SmartObject as shown below.
4. From the Designer, right click the Customer Item view, select Generate Forms. On the Generate Forms page, type Customer as the form name and click OK.
Test the solution by running the Customer form, clicking the Region ID field and selecting an item from the subview.
1. From the Designer, select the Customer form and click Run.
2. To test the Region lookup control, click the ellipsis in the Region ID field.
3. The Region List opens as a lookup list. Double click Region 2 to select it from the list.
4. Region 2 gets added to the Region ID field.

Review

You learned how to use the Lookup control on a form to show a subview with the list of items (lookup information) and then select an item to populate a field on the form.