Before You Begin

This 15-minute tutorial shows you how to create cascading drop-down lists in an Oracle Visual Builder page.

Background

“Cascading drop-down lists” imply that a value in the first drop-down determines what appears in the second drop-down; namely, by selecting a country in the first drop-down, you get a list of cities in that country in the second. We’ll achieve this by adding an event to the first list that triggers an action chain to populate the second list. We’ll also add a third component to display the selected city's population.

You should be familiar with the basics of creating an application, adding components to pages, and creating action chains. If you haven't already, you might want to complete the Create a Web Application in Oracle Visual Builder workshop, or equivalent.

What Do You Need?

• Access to Oracle Visual Builder
• A supported browser

Create a Web Application

1. In the web browser, log in to Oracle Visual Builder.
2. On the Visual Applications page, click New.

   

3. In the Create Application dialog, enter:
   • Application Name: Lists Application
   • Description: Tutorial application

   The Application ID text field is automatically populated, based on the Application Name. The Application template field is set to Empty Application.

4. Click Finish.

   The application is created and opens on the Welcome page.

5. Click the Web Apps tab, then click + Web Application (or click the + sign at the top of the pane).
6. In the Create Web Application dialog, enter listwebapp in the Application Name field. Select None for Navigation Style, then click Create.

   The application opens on the main-start page.

Import Data for Two Business Objects

In this step, you'll import data from a zip file to create two business objects for the application.

1. Click this link and download the EUData.zip file. Feel free to review the contents of the zip file.
2. Click the Business Objects tab.
3. Click Menu at the top of the Business Objects pane and select Data Manager.
4. Click Import Business Objects.
5. On the Upload File step of the import wizard, click the Drag and Drop area to select the EUData.zip file, or drop the file into the area. Click Upload.
6. When the upload succeeds, click Next.
7. On the wizard's Business Objects step, you'll find that two business objects are created: City and Country. Click Next.
8. On the wizard's Fields step, you'll need to make a change to the City object, which is selected by default . In the first row (country), click the number symbol in the Type column. In the dialog, change the setting as follows:
   • Type: Reference
   • Referenced Business Object: Country
   • Display Field: name

   

   Click OK .

9. Click Finish.
10. In the Applying Changes dialog, click Close after the data import finishes successfully.
11. Click the Country business object in the Navigator, then click the Data tab to view the imported data. Do the same for the City business object.
12. In the Business Objects pane, click +, then select Business Object Diagram.
13. In the Create Business Object Diagram dialog, enter EUDiagram in the Diagram name field and click Create.
14. In the Diagram's Properties pane on the right, click Select All to view the relationship between the two business objects you created. The line between the City and Country objects shows the many to one relationship between them, in which one country has many cities:

    

Create a Drop-down List of Countries

1. Click the Web Apps tab in the Navigator.
2. Expand the listwebapp and main nodes, then click main-start to open the Page Designer.
3. In the Components pane, under Controls & Navigation, locate the Heading component and drag it onto the page.
4. In the Properties pane, enter Countries and Cities in the Text field.
5. In the Components pane, type "sing" in the search box, then drag the Select (Single) component onto the page.
6. In the Property pane's Quick Start tab, select Add Options.
7. On the wizard's Locate Data step, select Country under Business Objects and click Next.
8. On the wizard's Bind Data step, select name to add it to the Label field, then select id to add it to the Value field.

   

9. Click Next.
10. On the Define Query step, click Finish.
11. With the Single Select component selected, click the General tab. Then, in the Label Hint field, enter Select Country.

    

Create a Drop-down List of Cities

1. From the Components pane, drag another Select (Single) component onto the page, below the Select Country component.
2. In the Properties pane, on the Quick Start tab, select Add Options.
3. On the wizard's Locate Data step, select City under Business Objects and click Next.
4. On the Bind Data step, select name to add it to the Label field, then select id to add it to the Value field.
5. Click Next.
6. On the Define Query page, click Finish.
7. With the Single Select component selected, click the General tab. Then in the Label Hint field, enter Select City .

Create an Action Chain to Populate the Cities List

To filter the city list, we need to create a page variable and assign it the selected country's ID. We'll use this page variable to create a filter criterion for the cities SDP (cityListSDP), to filter out cities that aren't in the selected country. An SDP is a service data provider that's bound to components like a List View, Table, or Select Single, to automatically handle data fetches for them whenever data needs to be refreshed.

1. Click the Select Country drop-down list, and on the Properties pane's Data tab, hover over Value and click the down arrow.
2. In the Variables dialog, click the Page node's Create Variable link to create a new page variable,
3. For ID, enter countryID, and for Type, select Number, then click Create. Now, when a country is selected, its ID is saved to this variable.

   Next, we need an event, action chain, and filter to populate the city list.

4. With the Select Country drop-down list selected, click the Events tab in the Properties pane.
5. Click + New Event and select On 'value-item' from the menu.

   

   You are taken to the Action Chains editor.

6. Drag the Assign Variable action from the Actions palette onto the canvas.
7. In the Properties pane, type city in the Variable field, then select cityListSDP.filterCriterion.

   

8. For the Value property, click its Click to add condition link to create a criterion to filter out the cities that aren't in the selected country.

   The Filter Builder appears under the Variable property for you to create the filter criterion. You should widen the Properties pane in order to better work with the Filter Builder.

9. In the Filter Builder, click the Attribute field after IF and select county from the dialog. Choose equals ($eq) from the Operator list, then type country in the second Attribute field and select $page.variables.countryID from the list.

   

10. Click Done.
11. Click Page Designer, then click Live to test the action chain.
12. Select a country from the Select Country list, then click the Select City list to view the cities that are in the selected country. Try this a few times.
13. When you're done, click Design to return to Design view.

Create a Type and Variable for the Selected City

To display the selected city's population, we'll store the selected city's data in a variable, then use that variable to provide the data for the component that shows the population.

First, we need to define a type for the variable so that it can store the data returned by the GET City endpoint. To store a city's data, the variable must be of the same type as the object that's returned by the endpoint.

1. Click the Types tab.
2. Click + Type and select From Endpoint.
3. In the Create Type from Endpoint wizard, expand the Business Objects and City nodes.
4. Select GET /City/{City_Id}, and then click Next.

   

5. In the Endpoint Structure list, select id, name, country, and population, and click Finish.
6. In the Properties pane, change the ID value from get_City to CityType.
7. Click the page's Variables tab, then click + Variable.
8. In the dialog, enter selectedCity in the Id field. From the Type drop-down list, scroll down and select CityType under Page. Click Create.

   

Create Another Field and Action Chain

1. Click the page's Page Designer tab. Ensure that the Design tab in the middle pane is selected.
2. In the Components pane, type "input" in the search, then drag the Input Number component onto the page, below the Select City component.
3. In the Properties pane, enter Population in the Label Hint field, and select the Readonly check box.

   

4. Click the Select City drop-down field, then click the Events tab, in the Properties pane.
5. Click + New Event and select On 'value-item' from the menu.

   The Action Chains editor opens.

6. In the Actions palette, type "if" in the search box, then drag the If action onto the canvas.
7. In the Properties pane, enter the following condition in the Condition field:

   typeof value !== 'undefined'

   This condition ensures that the rest of the action chain won't be executed until the user selects a value from the Select City drop-down list.

8. In the Actions palette, type "rest" in the search box, then drag the Call REST action into the Add Action area of the If action.
9. With the Call REST action selected on the canvas, in the Properties pane, click the Select link next to Endpoint. In the Select Endpoint dialog, expand the Business Objects and City nodes, then select GET City/{City_ID}. Click Select.
10. In the Properties pane, click the Assign link next to Input Parameters.
11. In the Assign Input Parameters mapper, drag key from Action Chain on the Sources side to City_Id on the Target side, then click Save.

    

12. To handle Call Rest errors, type "if" in the Actions palette's search box, then drag the If action over the Call Rest action and drop it into the Create Error Handler area that appears:
    

    

13. Type "fire" in the Actions palette's search box, then drag the Fire Notification action into the Add Action area of the if (true) condition.
14. In the Properties pane, enter the provided text for these fields:
    Summary: Error
    Message: An error occurred retrieving the City's data.
    
15. To save the city's data to the page variable, type "var" in the Actions palette's search box, then drag the Assign Variables action under the Call Rest action's error handler:
    

    

16. With the Assign Variables action selected on the canvas, in the Properties pane, type sel in the Variable field, then choose selectedCity from the list.
17. Hover over the Value field that appeared and click the down arrow. Under the Action Chain node, expand the Call Rest action's return object (callRestBusinessObjectsGetCityResult) and select body.

    

    Here's the completed action chain:

    

18. Click Page Designer, then select the read-only Population component.
19. In the Properties pane, click the Data tab, then hover over the Value field and click the down arrow that appears.
20. Under the Page node, expand the selectedCity object and select population.
    

    

    The following appears in the Value field:

    {{ $variables.selectedCity.population }}

Test the Application

1. Click the Preview icon to run the application in a new tab or window.
2. Select a country from the Select Country list, and then select a city from the Select City list.
   

   The population of the selected city appears in the Population field.

3. When you're done, close the tab or window.

Want to Learn More?

• Add Events to Components in Developing Applications with Oracle Visual Builder