Pick Item from Listing

Audience: Low-code Engineers

Skill Prerequisites: Actions, Forms, Listings

Opens a Listing module in a popup on top of a form. When the user clicks a row, the popup closes and the values of that row are copied into form fields. Use it when a dropdown isn't enough, for example to search a large list or to fill several fields at once.

The user can search, filter and page through the listing as usual before picking a row.

note

In PAA 1.28, Pick Item from Listing replaces the removed Browse Data from Listing action. Existing Browse Data from Listing actions keep working and now run as Pick Item from Listing. See Browse Data from Listing.

Typical Use Cases

• Pick a customer from a searchable listing and fill in their name, email and phone
• Choose a product and copy its code and price into an order form
• Replace a dropdown or autocomplete when the list is long or you need several values from the same row

Don't use it to

• Pick a single value from a short list. Use a dropdown field instead.
• Pick several rows at once. The user picks one row per click.
• Just show a listing in a popup. Use Show Listing And Stop Execution instead.
• Pick an item from a listing button or an API endpoint. It's only available in forms.

Related Actions

Action Name	Description
Show Listing And Stop Execution	Shows a listing on the page or in a popup, without copying values.
Open Form Popup And Stop Execution	Opens a Form module in a popup.
Get Data Query	Stores a listing's query and filters in tokens.

Input Parameter Reference

Parameter	Description	Supports Tokens	Default	Required
Listing Module	The Listing module to open in the popup. It can be on any page of the site.	No	empty	Yes
Display Listing Buttons	Shows the listing's buttons in the popup. When it's off, the listing opens in picker mode and its item buttons are hidden.	No	false	No
Mappings	A list of Form Field and Listing Field pairs. When the user picks a row, each form field gets the value of its listing field.	No	empty	No

How it works

1. The action opens a popup with the listing's page inside it, without the site's skin. The listing always shows its Data Table view and is always visible, whatever its Display Mode is.
2. The user searches or filters, then clicks a row.
3. For each mapping, the value of the listing field is copied into the form field.
4. The popup closes. The user stays on the form and can keep editing or submit it.

The form isn't submitted and no other actions run. Use the form's own buttons and events to process the picked values.

Browse Data from Listing

Up to PAA 1.27, forms had a Browse Data from Listing action (BrowseActionGrid), marked as obsolete in 1.27. It did the same job, but opened the listing with the legacy listing views. In PAA 1.28 it's removed from the list of actions, and BrowseActionGrid is now another name for Pick Item from Listing:

• Actions that use BrowseActionGrid still load and run. They have the same parameters, so your Listing Module, Display Listing Buttons and Mappings are kept.
• They now open the listing the way Pick Item from Listing does, in its Data Table view with the current listing views.
• You can't add a new Browse Data from Listing action. Add Pick Item from Listing instead.

If an older form opened a listing that only has legacy views, add and enable a Data Table view on that listing.

Considerations

• Put it last. Actions after this one don't run.
• The listing needs a Data Table view. The popup always opens the Data Table view. If the listing doesn't have it, or it's turned off, the popup shows an error. Legacy listing views aren't supported.
• Mapped values replace what's typed. Every mapped form field is overwritten, even if the listing value is empty.
• Map by field. Listing Field lists the fields of the selected listing. Pick the Listing Module first, then add the mappings. If you change the listing, check the mappings again.
• Lock into Edit Mode. Clicking a row doesn't pick it when the listing has Lock into Edit Mode turned on, or while a row is being edited inline.
• Permissions. The popup loads the listing's page as the current user. The user must be allowed to see that page and module.
• Invalid module. If the selected listing no longer exists, the action fails with Invalid grid module.
• Conditions. To open the popup only in some cases, give it a condition, for example "[CustomerId]" == "". See Common Parameters.

Examples

tip

To understand how to use the below examples, please see Running Examples.

1. Pick a customer for an order

Add this action to a "Choose Customer" button on an order form. It opens the customers Listing module 1234 in a popup. When the user clicks a customer, the form's CustomerName and CustomerEmail fields are filled in.

The ActionGridField values are the IDs of the listing fields. The easiest way to set them is to import the action, then pick the fields in Mappings.

{
    "Title": "Pick Item from Listing",
    "ActionType": "Listing.PickItem",
    "Description": "Choose a customer for the order",
    "Parameters": {
        "Grid": "1234",
        "DisplayButtons": false,
        "Mappings": [
            {
                "ActionFormField": { "Value": "CustomerName" },
                "ActionGridField": { "Value": "11" }
            },
            {
                "ActionFormField": { "Value": "CustomerEmail" },
                "ActionGridField": { "Value": "12" }
            }
        ]
    }
}

Learn More

See this at work on the Campfire Website.

Revised 09/27/2026