Create Lookup Window in m-Painter
The Lookup Window is popular because:
- Lookup Windows are a viable alternative to dropdown lists. mrc recommends using dropdown lists when there are less than 100 options to select. Lookup Windows have no size limitation.
- Lookup Windows allow your user to filter and paginate through records easily.
- Lookup Windows can return multiple values to multiple inputs on a single form.
This example will focus on how to create a Lookup Window link within a Report Template; however this process can be utilized in Retrievals and Maintenance applications, as well.
Step 1 — Create a multiple record retrieval to serve as your lookup window
To begin, we first need to create a Multiple Record Inquiry application that will serve as our Lookup Window List. This application should contain all of the necessary fields you wish to pass between the applications. Once the application has been built and compiled, open m-Painter. Select the field that you wish to serve as the link, and click the "Link" button from the toolbar. Set the "Link Type" dropdown to "Return Data". Click "OK". Click "Save". Your retrieval has now been set up to return data to the calling app. This step only needs to be done once per lookup list.
Step 2 — Create the lookup window
Next, open m-Painter for the report we will be adding the Lookup Window link to and navigate to the prompt page. Left click where you would like to insert the lookup window link. Note: It does not matter where you put the link, it is completely up to your preferences.
From here click on the "Lookup" button.
This will cause a dialog box to appear. Each option is outlined below:
Lookup Retrieval — This dropdown box shows you each retrieval you have available within this Data Dictionary. Since the source for your Lookup Window must be a retrieval, please select the appropriate application (i.e. the one you built in the previous step) from this list.
Link Text — This option allows you to customize the text for your Lookup Window link. While you can choose whatever you wish, most users will call it "Customer Lookup" (Replacing Customer with the appropriate subject of the Lookup Window).
Selected App — This box will automatically populate when you select an application from the "Lookup Retrieval" drop-down box.
Additional URL Parameters — This input box allows you to pass any additional parameters to your retrieval. For instance, if you only wanted to show records where the STATE (Field: CSTTE) began with the letter "I", you would pass the following parameters: "&rls_CSTTE=SW&val_CSTTE=I". This tells the retrieval to use the "SW" record selection on the CSTTE field and pass the letter "I" as the value of the CSTTE.
Fields from Retrieval — This drop-down shows you all of the fields available within your Lookup Window Retrieval. Similarly, Current App Fields shows a drop-down list of all of the fields from your current application. You will want to match up the fields you wish to return. For example, in my example I want to pass both the state and the customer name to my report. My report is set up to accept state on R001, and customer name on R002. I selected STATE from the first list, R001 from the second list and clicked Add. I did the same thing for CNAME and R002, then clicked Add. You can see my results from adding the first set of matched up fields (STATE and R001) below.
Dialog Height & Dialog Width — This option allows you to control, in pixels, how large your Lookup Window will be.
Once you have made all of your specifications, please click "OK", then click "Save". Run your application.
At runtime, when you engage the Lookup Window link, you will notice that the background dims. This is intentional as it focuses your user on the Lookup Window. Your end user can easily move this Lookup Window around the screen to see background data. When the user finds the record they wish to select, they simply click on it. The Lookup Window will disappear and the value they selected will be returned to the form (based on the fields you matched within m-Painter).
- This functionality is not available within the following templates:
- Grid Maintenance
- Work-with Maintenance (Search)
- You can only reference Lookup Windows from within the same data dictionary as your application.
- The method of creating Return Data functionality via the Maintenance screen will continue to work to support older applications, but has been deprecated.