C3 AI Documentation Home

Filter data using contextVars

UI components often need to filter or fetch data based on the current page context. The contextVars field in a component dataSpec lets you declare a variable, define where its value comes from, and use that variable in filters, entity lookups, or other configuration fields.

Use contextVars when:

  • A component must access a dynamic value - such as a URL parameter - to filter data or look up a specific record.
  • You want to avoid writing custom logic to handle dynamic filters.

Although you can use page parameters for simplicity, you can use any type of UiSdlDynamicValueSpecParam, including query parameters, route variables, or custom application context.

This topic shows two examples that demonstrate contextVars in action.

Filter a data grid by location

This example configures a UiSdlDataGrid to display WindTurbine records. The grid reads the location page parameter from the URL and filters the data to show matching records.

The contextVars block in the JSON configuration defines a variable and sets its value using a parameter from the page URL. Add a new route that includes the matching parameter, myUrlParam, which the contextVars block references.

CSV
targetModuleName,targetPageName,name,urlPath
uiprototype,PageLayout,/,/
uiprototype,PageLayout,/home,/home
uiprototype,PageLayout,/{{myUrlParam}},/{{myUrlParam}}

Multiple entity component configuration

This configuration sets up the UiSdlDataGrid component to filter records based on the location page parameter.

JSON
/* examplePackage/ui/c3/meta/examplePackage.ContextVarsGrid.json */

{
  "type": "UiSdlConnected<UiSdlDataGrid>",
  "component": {
    "paginationConfig": {
      "pageSize": 2,  // Show 2 records per page
      "pagination": true  // Enable pagination controls
    },
    "dataSpec": {
      "dataType": "WindTurbine",  // Backend type to fetch
      "filter": "location == '${location}'",  // Filter using contextVar
      "actionName": "fetch",  // Fetch multiple records
      "columnFields": [  // Configure visible columns
        { "fieldName": "id", "label": "ID" },
        { "fieldName": "location", "label": "Location" },
        { "fieldName": "manufacturer", "label": "Manufacturer" },
        { "fieldName": "manufacturerDate", "label": "Manufacturer Date" }
      ],
      "contextVars": {
        "location": {  // Declare a context variable named location
          "type": "UiSdlPageParam",  // Get the value from the URL
          "path": "myUrlParam"  // Use the value after the base URL
        }
      }
    }
  }
}

This configuration defines a location variable in the contextVars block. The component retrieves the variable’s value from the page parameter in the URL. The filter clause uses ${location} to insert the variable directly into the filter expression. The grid then displays only the records where the location field matches the value provided in the URL.

Display a single entity by ID

This example configures a UiSdlDefinitionList to display a single WindTurbine record. The component reads the page parameter from the URL and uses it as the entityId.

Navigate to a URL like:

Text
https://<cluster>/<env>/<app>/<location>

For example, if the URL ends in /Boston, the component fetches and displays the WindTurbine record with ID Boston.

Single entity component configuration

This configuration sets up the UiSdlDefinitionList to fetch a single record based on the page parameter.

JSON
/* examplePackage/ui/c3/meta/examplePackage.ContextVarsDefinitionList.json */

{
  "type": "UiSdlConnected<UiSdlDefinitionList>",
  "component": {
    "dataSpec": {
      "dataType": "WindTurbine",  // Backend type to fetch
      "entityId": "${location}",  // Use contextVar as entity ID
      "fields": [  // Configure visible fields
        {
          "label": "Manufacturer",
          "fieldName": "manufacturer",
          "labelIcon": "info-circle",
          "subInfo": {
            "type": "UiSdlDefinitionListSubInfoFieldSetting",
            "fieldName": "manufacturerDate",
            "placeholder": "--"
          }
        },
        {
          "label": "Location",
          "fieldName": "location",
          "labelIcon": "map",
          "subInfo": {
            "type": "UiSdlDefinitionListSubInfoFieldSetting",
            "fieldName": "manufacturerDate",
            "placeholder": "--"
          }
        },
        {
          "label": "Status",
          "fieldName": "status",
          "labelIcon": "info-circle"
        }
      ],
      "contextVars": {
        "location": {  // Declare context variable named location
          "type": "UiSdlPageParam",  // Get the value from the URL
          "path": "myUrlParam"  // Use the value after the base URL
        }
      }
    },
    "orientation": "HORIZONTAL",  // Render fields horizontally
    "divider": true  // Add a divider between sections
  }
}

This configuration defines a location variable in the contextVars block. The component retrieves the variable’s value from the page parameter in the URL. The entityId field uses ${location} to look up a single record in the backend where the ID matches the URL value. The DefinitionList component then displays the configured fields from the matching record.

Was this page helpful?