How To: Configure the Picker control to use another control's data to filter the results

This topic shows how to configure a Picker control to use another control's data to filter results displayed in the picker. Sometimes referred to as "cascading" controls, data selected in the first control acts as a filter for data displayed in the second control. In this example, you select a value from a drop-down list control, which filters the values displayed in the picker control.

The Country drop-down list value filters the options displayed in the City picker control

Scenario

You have an online form containing two controls for selecting a state, and city within the state. As a convenience, you configure the two controls to cascade, where the state selected in the first control filters the cities displayed in the second control.

Steps

In this scenario, you create two SmartObjects, one for the state records and one for the city records. You create an association between the two SmartObjects. You create an editable list view and add the two controls. (The editable list view allows you to add several rows for testing.) You complete the example with the following:

  • The city (picker) control uses the state (drop-down) list control as its parent filter, with a common property linking the two controls.
  • A rule disables the city (picker) control as the view first loads.
  • A rule enables the city (picker) control after someone selects a state.

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 Configure the Picker control.

  1. In the Designer, create new categories to store your work.
  2. Create two SmartBox SmartObjects, using the tables below as a guide.
    State
    This SmartObject stores the state records.
    PropertyData Type
    IDAutonumber
    StateText
    City
    This SmartObject stores the city records.
    PropertyData Type
    IDAutonumber
    CityText
    StateIDNumber
    1. Create a SmartBox SmartObject and name it
      State
      then add the following property:
      State (Text).
      State SmartObject
    2. Create a SmartBox SmartObject and name it
      City
      then add the following properties:
      City (Text)
      StateID (Number).
      City SmartObject
  3. Edit the City SmartObject and add the following associations:
    • One-to-many association between the City and State SmartObjects

    In this step, you associate the City SmartObject with the State SmartObject. Associating SmartObjects creates a link between the two data sources, typically through a common property (such as an ID or other unique value).

    1. To add the association, edit the City SmartObject.
    2. Click the Associations tab, then click Add. On the SmartObject screen of the Add Association wizard, select the State SmartObject and click Next.
    3. On the Association screen, confirm your screen matches the image below to create the one-to-many association. Click Next.

      4. Next, you link a property from the City SmartObject to a property in the State SmartObject. This link creates the association that allows you to select a state from a drop-down list control, and use that value as a filter for cities displayed in the picker control.

    4. On the Relationships screen, select the StateID property and click Assign.

    5. On the Assign property (StateID) screen, select the ID property of the State SmartObject, and click OK.
    6. You should see the StateID property (from the City SmartObject) is now bound to the State (SmartObject): ID property. Click Finish to save the association settings.
    7. The Associations screen displays the new one-to-many relationship. Click Finish to save and exit.
  4. Generate an editable list view from the State SmartObject. Generate an editable list view from the City SmartObject. Run each view and add records to the City and State SmartObjects using the table below as a guide.
    Editable List View
    IDState
    [Auto]California
    [Auto]Washington
    Editable List View
    IDCityStateID
    [Auto]Los Angeles1
    [Auto]San Diego1
    [Auto]Seattle2
    [Auto]Redmond2
    1. Right-click the City SmartObject and select Generate Views.
    2. Check the box below Editable List to create the City Editable List view. The name is populated by default. Click OK.
    3. Repeat the steps above and create an editable list view for the State SmartObject.
      • SPLIT HERE Run both views and enter at least two records using the City Editable List view, and at least three records using the Country Editable List view. Run the Country Editable List view first because the City Editable List view is dependent on the data you create in the Country Editable List view. To add sample data to the Country Editable List view, right-click the view and select Run. Click Add and type a value in the Country field. Click Add again to add more items. When you are done, click Save.

        To add sample data to the City Editable List view, right-click the view and select Run. Click Add, type a value in the City field and select a value from the Country menu. The Country menu shows the data you created in the Country Editable List view because you associated the two SmartObjects. Click Add again to add more items. When you are done, click Save.

        Editable List View
        IDState
        [Auto]California
        [Auto]Washington
        Editable List View
        IDCityStateID
        [Auto]Los Angeles1
        [Auto]San Diego1
        [Auto]Seattle2
        [Auto]Redmond2

    5. Configure the Picker control

    In this step, you configure the Picker control to use the selected value from the Drop-Down List control to filter the results returned by the picker.

    1. Configure the Picker control. In this step, you generate an Item view for the City SmartObject and configure the Picker control to use the value you select as the country to filter the cities.
      1. Right-click the City SmartObject and select Design View.
      2. In the General tab, name the view
        City Item
        and keep the Item View type. Click Create.
        Create Item View
      3. Drag the CountryID field from the Fields onto the canvas and drop it into a cell. Note the Name in the Detail section of the Properties contains Drop-Down List, and the Country SmartObject is automatically configured as the Data Source for the control. This is because of the association you configured between the City and Country SmartObjects earlier.
      4. Drag the City field from the Fields onto the canvas and drop it into a cell. Select the control, click the Change Control icon, select Picker from the list, and then click OK.
      5. Next configure the data source for the Picker control by clicking the ellipsis next to SmartObject in the Data Source section.
      6. The Configure Data Source dialog opens. Click the ellipsis next to SmartObject.
      7. Expand the folders where you saved the City SmartObject. Select the SmartObject and click OK.
      8. Specify SmartObject properties on which you want to search when you type a value in the picker at runtime. Uncheck All next to Filter Properties and then mark the check box next to City.
      9. Specify the SmartObject property to use when you save values in the picker. You want to use this property to display when you list the countries and cities. Select City from the drop down list next to Identifier.
      10. Specify the SmartObject property (text) to display at runtime. Keep the City value next to the Display field.
      11. Next you want to select and configure the control (parent control) to use to filter the City picker's results. Check the box next to Filter the data according to another control's value. Select Country Drop-Down List next to Parent Control and select CountryID as the Child Join Property. The value of the Country Drop-Down List control is used to filter the results for the City control. The Child Join Property is the SmartObject property on the current (City) control that is used to filter the data. This property links the parent data to the child data and needs to match the parent join property. Click OK to save the configuration.
      12. Uncheck the box next to the Allow Multiple option. You don't want to allow the control to save and load multiple values.
    2. In the next step you edit the When the View executed Initialize rule to disable the Picker control when the view loads and you edit the When CountryID Drop-Down List is Changed rule to enable the Picker control when a value is selected in the Country Drop-Down List control. You do this to prevent people from searching for a city without selecting a country first.
      1. To disable the Picker control when the view loads, on the Rules page select the When the View executed Initialize rule and click Edit Rule.
      2. Select the Actions tab, click Disable a control in the Visibility section, and then select City Picker. Click OK to save the rule.
      3. To enable the Picker control after a value is selected in the Country control, on the Rules page select the When Country Drop-Down List is Changed rule and click Edit Rule.
      4. Select the Actions tab, click Enable a control in the Visibility section, and then select City Picker. Click OK to save the rule.
      5. Click Finish to save the view.
    3. Test your view by running the City Item view. Select a country using the drop-down list and then search for a city using the Picker control. Verify that only cities belonging to the selected country display.
      1. To test the view, select the City Item view, then click Run.
      2. Select a value from the Country drop-down list, click the search icon in the City control, and then click the search icon on the Search dialog. Note the results are filtered according to the country you select.
Review

Use the Picker control to filter return values according to another control's value. You can use rules to enable and disable a control to ensure people don't search for a value in the Picker control before they select a value in the Drop-Down List control. See Picker control and Using the Picker control for more information about configuring the control and how to use it.