ValuePicker

• Configuring ValuePicker
  • Configuring ValuePicker without data
  • Using the label component to present items
  • Using an arbitrary collection component to present predefined list
  • Using the combobox component to present selectable items
  • Using the slider component to navigate numeric values
• ValuePicker orientation

ValuePicker is a widget that allows users to step or play through a list of values. ValuePicker widget can be configured with an optional collection, label, combobox or slider control to help users navigate values.

Similar to a media player, values can be interactively stepped through using the next and previous buttons. ValuePicker can also be set to automatically progress (play) through an ordered list of items at a preset interval.

Configuring ValuePicker

ValuePicker can be configured in variety of ways, depending on your use case. The following are the five possible configurations of the ValuePicker widget.

1. Configuring ValuePicker without data

It is important to note that the ValuePicker widget is not associated with a View nor does it necessarily require data. In the example below, the ValuePicker is added to the View's UI without any assigned data.

const valuePicker = new ValuePicker();
view.ui.add(valuePicker, "top-right");

Since the widget is not associated with any data, it is necessary to listen and respond to widget events generated by the widget. This could be useful when data is not static like positional changes for bus features currently in service, for example.

valuePicker.on("play",     () => { console.log("user clicks play"); })
valuePicker.on("pause",    () => { console.log("user clicks pause"); })
valuePicker.on("previous", () => { console.log("user clicks previous"); })
valuePicker.on("next",     () => { console.log("user clicks next"); })

2. Using the label component to present items

Consider using the label component to step through a fixed list of predefined values like land use zones. In the following snippet a ValuePicker is added to the View UI containing three coded land use zones.

const labelComponent = {
  type: "label",
  items: [
    { value: "ind", label: "Industrial" },
    { value: "res", label: "Residential" },
    { value: "com", label: "Commercial" }
  ]
};

const valuePicker = new ValuePicker({
  component: labelComponent,
  values: ["ind"]
});
view.ui.add(valuePicker, "top-right");

The user's interaction can be handled by monitoring the values property.

reactiveUtils.watch(
  () => valuePicker.values,
  (values) => console.log(`The land use zone code is: ${values[0]}`)
);

3. Using an arbitrary collection component to present predefined list

It may be required to step through a fixed collection of items like extents, bookmarks, or basemaps. If only the play, next and previous buttons are required then the collection component may be used. The collection component consists of the same user interface as option 1 above with the distinction that the current item is accessible and tracked.

In the following example, a ValuePicker is created and added with a collection of three items. ValuePicker is initialized with starting value of "hybrid". Since "hybrid" is the first item in the collection only the next button will be enabled.

const valuePicker = new ValuePicker({
  component: { // autocasts ValuePickerCollection when type is "collection".
    type: "collection",
    collection: ["hybrid", "oceans", "osm"]
  },
  values: ["hybrid"]
});
view.ui.add(valuePicker, "top-right");

As the user clicks the next, previous, and play buttons the values property will update. This property can be monitored as demonstrated below.

reactiveUtils.watch(
  () => valuePicker.values,
  (values) => console.log(`The current basemap is: ${values[0]}`)
);

4. Using the combobox component to present selectable items

Consider using the combobox component when a searchable dropdown list is required. In the following snippet the ValuePicker widget is added to the View UI containing three coded land use zones.

const valuePicker = new ValuePicker({
  component: { // autocasts ValuePickerCombobox when type is "combobox".
    type: "combobox",
    placeholder: "Pick Zoning Type",
    items: [
      { value: "ind", label: "Industrial" },
      { value: "res", label: "Residential" },
      { value: "com", label: "Commercial" }
    ]
  },
  values: ["res"]
});
view.ui.add(valuePicker, "top-right");

As demonstrated in option 3 above, the user's interaction can be handled by monitoring the values property.

reactiveUtils.watch(
  () => valuePicker.values,
  (values) => console.log(`The land use zone code is: ${values[0]}`)
);

5. Using the slider component to navigate numeric values

The slider component, as the name suggests, appends a slider to end of the ValuePicker widget. The slider is ideal for users that need to select a value within a fixed numeric range. For example, the snippet below presents a ValuePicker with a slider for picking a layer's opacity. The starting value is 50%.

const valuePicker = new ValuePicker({
  component: {                                                // autocasts ValuePickerSlider when type is "slider".
    type: "slider",
    min: 0,                                                   // Start value
    max: 100,                                                 // End value
    steps: [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100],      // Thumb snapping locations
    minorTicks: [5, 15, 25, 35, 45, 55, 65, 75, 85, 95],      // Short tick lines
    majorTicks: [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100], // Long tick lines
    labels: [0, 20, 40, 60, 80, 100],                         // Long ticks with text
    labelFormatFunction: (value) => `${value}%`               // Label definition
  },
  values: [50]                                                // "current value"
});
view.ui.add(valuePicker, "top-right");

Note that steps (positions the slider thumb snaps to), minorTicks, majorTicks and labels are independent of each other and optional.

The following code will watch for changes and apply the user's modification to a feature layer.

reactiveUtils.watch(
  () => valuePicker.values,
  (values) => {
    featureLayer.opacity = values[0] / 100;
  }
);

ValuePicker Orientation

By default ValuePicker is oriented horizontally. ValuePicker (with the exception of combobox and label components) can be oriented vertically. The following snippet demonstrates how to orient a collection based ValuePicker vertically.

const valuePicker2 = new ValuePicker({
  layout: "vertical", // default is "horizontal"
  component: {
    type: "collection",
    collection: ["hybrid", "oceans", "osm"]
  },
  values: ["hybrid"] // Set the initial value to "hybrid"
});