List widget

The List widget displays data records in a custom list view. It uses a card design as a container for a few short descriptions of related information with the option to include a button to view additional details. You can choose from several templates to build the card layout. The templates include image, button, and text widgets. You can also choose a blank template to design your own. The data source for the list is defined by a feature layer. Each item card in the list represents a record, and the widgets on a card can be used to display the record’s attributes. To design the list, you can customize the style settings and modify the layout of the first card to update all the cards in the list.

Examples

Use this widget to support app design requirements such as the following:

• You want to build an app that allows users to select a record in the list and view it on the map.
• You want to display records from a data source in a custom list view. The records to display must meet certain criteria.
• You want to provide a list for users to interact with, such as filtering the list, sorting the list with predefined options, and selecting records in the list.

Usage notes

When you add a List widget, first choose a template design for the item cards in the list, and click Start. On the canvas, the first item in the List widget is activated and you can modify the layout of the widgets within it or add more by dragging widgets from the Insert panel into the first card. Currently, the List widget only supports Text, Button, and Image widgets.

The List widget requires a data source. You can use the List widget on a page with or without a displayed map. If you include a Map widget that uses the same layer, clicking a feature in the list highlights the corresponding feature in the map. When designing the contents of item cards in the list, specify what you want to display by configuring the widgets in the first item, selecting respective dynamic content to populate records from the connected data source. (By default, widgets that you add to the list inherit the list’s data.) You can also set actions for a List widget to interact with other widgets in your app, such as zooming to the selected feature on a map in a Map widget or displaying the selected feature’s attributes in a Feature Info widget.

If you configure the List widget with multiple states (Default, Hover, and Selected), a Linked to button appears when you select the nested widgets for custom layouts. The button indicates whether the widget’s settings are isolated or synchronized across the states.

• For synchronized widgets, the widget content and style settings (background, border, and shadow) are the same, and the size and positions can be different across states.
• For isolated widgets, you can configure properties without affecting other widgets in another state.
• To use the same widget in another state or synchronize the widget’s size and position as well, select the widget and apply it to the target state.
• When you delete a synchronized widget, the same widget in different states is also deleted unless you isolate the widget first.

Search methods

The List widget's search tool uses different methods to retrieve search suggestions and search results.

The widget's search tool uses full-text search to retrieve search suggestions. Full-text search is an efficient search method that uses full-text field indexes, which split up records into small units, such as individual words. For example, imagine you have a layer of United States Post Office locations with a name field containing the names of every post office location. The index splits the name Highland Station Baltimore Post Office into five individually searchable words: Highland, Station, Baltimore, Post, and Office. If you enter a search phrase made up of any combination of those words (or just the first part of any of them) such as Baltimore Office, Highland Baltimore, or Stat Balt Office, you get that office in the search suggestions.

Full-text field indexes are automatically generated for hosted feature layers when you select them as search fields for the Search, List, or Table widget if you are the owner of the hosted feature layer or an organization administrator.You can also manually add indexes to attribute fields on the layer's item details page. If you have layers with no indexes and you do not have permission to edit the layers, the List widget finds suggestions using START WITH abc%, meaning the widget looks for records that start with the search phrase. This is a less efficient search method.

To retrieve search results, the widget uses CONTAIN %abc%, meaning the search phrase can be anywhere in the record. For example, you can search for alt to get Baltimore, Salt Lake City, and Alton in search results.

Caution:

Full-text search is new with the Experience Builder October 2023 release and is a breaking change. Before this release, the widget used CONTAIN %abc% to retrieve both suggestions and results. Unlike CONTAIN %abc% queries, full-text search cannot find search phrases located in the middle of words. In the example above, searching for altimor or ighlan will not return the expected post office in search suggestions. Learn more about searching for features in maps and apps.

Settings

The List widget includes the following settings:

• Select a template—Choose from predefined list designs or start with an empty list template. (If you choose a template, you can customize its appearance later.)
• Data—Specify the data to include in the list.
  • Select data—Select the data source for a feature layer with features to show in the widget. You can only select one data view for one feature layer. In the data view settings, you can filter the data to restrict what appears in the widget, sort the data to display list items in a particular order, or specify record limitations.
  • No data message—Decide what message to show when the widget contains no data, such as when the user applies a filter.
  • Last update text—Optionally, when the data source has Auto refresh turned on, exclude the last update label that indicates when the data was refreshed in the app.
• Arrangement—Define how to display the items in the list.
  • Layout—Display items in a row, column, or grid list.
  • Item width or height—Specify the size of list items.
    • For a row list, define the list item’s width by typing a precise pixel number in this setting or dragging the resize bar on the canvas. The item’s height is defined by the widget’s height.
    • For a column list, define the list item’s height by typing a precise pixel number in this setting or dragging the resize bar on the canvas. The item’s width is defined by the widget’s width.
    • For a grid list, define the list item's width and height by typing precise pixel numbers in each setting or dragging the resize bars on the canvas. You can also define the list item's width by percentage of the widget's width.

    Note:

    When the list uses a custom layout for medium- or small-screen devices, you can customize the size of list items. Icons in this setting indicate which screen size (large, medium, or small) the configuration applies to.

  • Lock width/height ratio—Lock the width/height ratio of list items when the widget is resized.
  • Alignment (Available for grid lists)—Align list items to the right, center, or left.
  • Horizontal or Vertical spacing—Define the spacing between list items in pixels. For a grid list, define both.
  • Paging style—Define how to load list items that don’t fit on the first page:
    • Scroll—Load more items when users scroll down in the list.
      • Scroll bar—Show a scroll bar.
      • Navigator—Include up and down or left to right navigation controls for scrolling the list. For Step, define the number of items or rows to scroll for each click in the navigator control.
    • Multi-page—Divide a long list into several pages using pagination. For Items per page, define the number of items to display on a page.
• States—Provide a visual representation to communicate the three states of list items: Default (default state for the item without user interaction), Hover (user initiates this state by pointing to a list item), and Selected (user selects the list item).

  Tip:

  To change the corresponding states for nested widgets, you can isolate the changes so they don't apply to all the states. Select the List widget, and click the button for the state you want to change. For the Layout setting, select Custom. Click a nested widget, click the Linked to button that appears, choose Isolate, and configure the nested widget's settings. (If you configure settings first and click Isolate, the changes will have already been applied to the other states.)

  • Background—Set the background for list items in their default state (no current user interaction). Choose a fill color or image. If you choose an image, you can position it within the list item’s border using Fit, Fill, Center, Tile, or Stretch. If you choose Fit, the background fill color appears around the image.
  • Border—Set the border for list items in their default state by choosing the border color, style (such as dashed or dotted), and width in pixels. You can style all sides of the border at the same time or style each of them separately.
  • Border radius—Change the radius size (by pixels or percent) to shape the corners of list items in their default state. Lock the settings to synchronize the radius of all four corners.
  • Hover—Specify whether the appearance of a list item changes when users hover over it. When the hover state is enabled, its settings appear in the configuration panel with options to change the background, border, and border radius of the hovered list item.
    • A Hover tab appears next to the first list item in the canvas, which updates to show how the item will appear when users hover over it. You can also add widgets or delete, resize, and reposition existing widgets for the hover state only.
  • Selected—Specify whether the item card in the list can be selected and how its appearance changes when users click to select it. When the selected state is enabled, its settings appear in the configuration panel with options to allow multiselect and change the background, border, and border radius of the selected list item. With Select mode, you can limit selections to only one item at a time (clicking another item clears the current selection) or allow users to select multiple items at the same time (clicking another item adds it to the current selection set).
    • A Selected tab appears next to the first list item in the canvas, which updates to show how the item will appear when users select it. You can also add widgets or delete, resize, and reposition existing widgets for the selected state only.
• Tools—You can include the following tools in the widget panel at run time:
  • Search—Allow users to search for records in the list.
    • Select searching fields—Choose one or more fields to search.
    • Exact match—Limit search results to only records that match the search phrase.
    • Hint—Provide a hint that appears as placeholder text in the search box to help users search for relevant values.
  • Sort—Provide a menu for users to sort the list by specific fields and sequence. Type a custom name for each menu option.
  • Filter—Add filters for users to interact with the list. When you set filters, the widget includes a reset button that resets the filters to their original states.
  • Refresh—Allow users to refresh the list to show the latest data. This setting is useful if you connect your list to a data source that is regularly updated.
  • Show selection—Allow users to update the list to only display the selected items.
  • Clear selection—Allow users to clear the selection of all selected items.
  • Show record count—Show counts of total and selected records.

  Note:

  The Show selection and Clear selection tools only appear when the Selected state is enabled.

Interaction options

This widget supports actions, which you can configure on the Action tab of the widget's settings.

You can configure message actions to create automatic interactions between widgets. For example, to make a Map widget automatically zoom to a feature when the user selects it with the List widget, you can add the Record selection changes trigger, select a Map widget as the target, and add the Zoom to action.

Turn on data actions to add buttons to the List widget's user interface for performing data processing tasks, such as exporting, zooming to, and setting filters. Users can run data actions for all data in the list or for selected features.

Note:

When users export data with the Export data action, only fields that are actively being used by the List widget are included in the export. This includes fields being used for dynamic text, dynamic images, and so on.