DataSource

The DataSource component manages fetching data from an API endpoint. This component automatically manages the complexity of the fetch operation and caching. To manipulate data on the backend, use the APICall component.

Properties

body

Set the request body. The object you pass is serialized as a JSON string.

completedNotificationMessage

Set the message to display when the data fetch completes.

This property customizes the success message displayed in a toast after the finished API invocation. The $result context variable can refer to the response body. For example, you can use the following code snippet to display the first 100 characters in the completed operation's response body:

 <DataSource
  id="ds"
  url="/api/shopping-list"
  completedNotificationMessage="Result: {JSON.stringify($result).substring(0, 100)}" />

errorNotificationMessage

Set the message to display when the there is an error.

This property customizes the message displayed in a toast when the API invocation results in an error. The $error.statusCode context variable can refer to the response's status code, while $error. details to the response body. For example, you can use the following code snippet to display the status code and the details:

 <DataSource
  id="ds"
  method="post"
  url="/api/shopping-list"
  errorNotificationMessage="${error.statusCode}, {JSON.stringify($error.details)}" />

headers

Set request headers. Pass an object whose keys are header names and values are header values.

id (required)

Set the ID used by other components to access the retrieved data in the valueproperty of a DataSource, or status info in the loaded and error properties.

inProgressNotificationMessage

Set the message to display when the data fetch is in progress.

method (default: "get")

Set the HTTP method.

Available values: get (default), post, put, delete, patch, head, options, trace, connect

nextPageSelector

When using DataSource with paging, the response may contain information about the previous and next page. This property defines the selector that extracts the next page information from the response deserialized to an object.

pollIntervalInSeconds

Set the interval for periodic data fetching. If the data changes on refresh, XMLUI will re-render components that refer directly or indirectly to the DataSource.

prevPageSelector

When using DataSource with paging, the response may contain information about the previous and next page. This property defines the selector that extracts the previous page information from the response deserialized to an object.

queryParams

Append key/value pairs to the URL.

rawBody

Set the request body with no serialization. Use it to send a payload that has already been serialized to a JSON string.

resultSelector

Set an object key to extract a subset of the response data.

The selector can be a simple dot notation path (e.g., value.results) or a JavaScript expression that processes the data (e.g., results.filter(item => item.type === 'active')). The selector has access to standard JavaScript functions like map and filter, and operates on the full response body.

Here is a sample response from the HubSpot API.

{
    "results": [
        {
            "id": "88903258744",
            "properties": {
                "company": "HubSpot",
                "createdate": "2025-01-03T23:38:47.449Z",
                "custom_notes": "Nice guy!",
                "email": "bh@hubspot.com",
                "firstname": "Brian",
                "hs_object_id": "88903258744",
                "lastmodifieddate": "2025-02-18T23:13:34.759Z",
                "lastname": "Halligan (Sample Contact)"
            },
            "createdAt": "2025-01-03T23:38:47.449Z",
            "updatedAt": "2025-02-18T23:13:34.759Z",
            "archived": false
        },
        {
            "id": "88918034480",
            "properties": {
                "company": "HubSpot",
                "createdate": "2025-01-03T23:38:47.008Z",
                "custom_notes": null,
                "email": "emailmaria@hubspot.com",
                "firstname": "Maria",
                "hs_object_id": "88918034480",
                "lastmodifieddate": "2025-01-03T23:38:59.001Z",
                "lastname": "Johnson (Sample Contact)"
            },
            "createdAt": "2025-01-03T23:38:47.008Z",
            "updatedAt": "2025-01-03T23:38:59.001Z",
            "archived": false
        }
    ]
}

This resultSelector builds an array of the properties objects.

<DataSource
  id="contacts"
  url="http:///{DOMAIN}/{CORS_PROXY}/api.hubapi.com/crm/v3/objects/contacts?properties=firstname,lastname,email,company,custom_notes"
  resultSelector="results.map(item => item.properties )"
  headers='{{"Authorization":"Bearer not-a-real-token"}}'

This List uses the array.

<List data="{contacts}" title="Hubspot Contacts">
  <Card gap="0" width="20em">
    <Text fontWeight="bold">
      {$item.firstname} {$item.lastname}
    </Text>
    <Text>
      {$item.company}
    </Text>
    <Text>
      {$item.email}
    </Text>
    <Text>
      {$item.custom_notes}
    </Text>
  </Card>
</List>

This resultSelector filters the array of the properties objects to include only contacts with non-null custom_notes.

<DataSource
  id="contacts"
  resultSelector="results.filter(contact => contact.properties.custom_notes !== null).map(contact => contact.properties)"
  url="http:///{DOMAIN}/{CORS_PROXY}/api.hubapi.com/crm/v3/objects/contacts?properties=firstname,lastname,email,company,custom_notes"
  headers='{{"Authorization":"Bearer not-a-real-token"}}'
  />

This Table uses the filtered array.

<Table title="HubSpot contacts" data="{contacts}">
  <Column bindTo="firstname" />
  <Column bindTo="lastname" />
  <Column bindTo="company" />
  <Column bindTo="email" />
  <Column bindTo="custom_notes" />
</Table>

transformResult

Set a function to perform a final transformation of the response data.

url (required)

Set the URL.

Events

error

This event fires when a request results in an error.

loaded

The component triggers this event when the fetch operation has been completed and the data is loaded. The argument of the event is the data loaded.

Exposed Methods

This component does not expose any methods.

Styling

This component does not have any styles.