Tab Content Examples

Purpose-built App plugins can include various types of tabs to display different content to users. This guide provides practical examples of each tab type and how to configure them in your app.

For concepts and architecture: See the Purpose-built App Deep Dive.

Overview

There are three main types of tabs you can include in a Purpose-built App:

Tab Type	Description	Use Case
content	Displays external content inside an iframe via a custom URL	Display web pages, dashboards, or custom web applications
customBlockTab	Displays a Custom Block plugin	Display custom UI/UX built with the Custom Block SDK
multiPageDashboardTab	Displays a specific page from a multi-page dashboard	Display Qualtrics dashboards with multiple pages

---

Content Tab

A content tab displays external content in an iframe. This is the most flexible option for displaying web pages, single-page dashboards, or custom applications.

Key Properties

Property	Type	Description	Required
type	string	Must be "content"	Yes
id	string	Unique tab identifier (human-readable recommended)	Yes
nameKey	string	Translation key for the tab name in the side navigation	Yes
href	string	URL to load in the iframe	Yes
iconName	string	Icon name from the available Tab Icons	Yes
themeType	string	Theme color when tab is active (e.g., "green", "blue")	Yes
order	number	Display order of the tab in the side navigation	No
URLAllowList	string[]	List of regex patterns for allowed URLs in the tab	No
activeForGlobalWrapperConfigTypes	object[]	Configuration for when this tab is active	No
configurationSettings	object	Settings for whether users can customize this tab	No
accessControls	object	Permissions required to view this tab	No

Use content tabs for: Single-page dashboards, web applications, or any external content accessible via URL. Use multiPageDashboardTab instead if you need to display a Qualtrics multi-page dashboard with multiple selectable pages.

Example: Tickets Tab

{
  "type": "content",
  "id": "TicketsView",
  "nameKey": "Portals.TicketsTab",
  "iconName": "Tickets",
  "href": "/tickets/app",
  "themeType": "green",
  "URLAllowList": ["/tickets/app*"],
  "activeForGlobalWrapperConfigTypes": [
    {
      "contextType": "Tickets"
    }
  ],
  "accessControls": {
    "AccountPermissions": ["AccountPermissions.useTickets"]
  }
}

Example: Dashboard Content Tab

{
  "type": "content",
  "id": "InsightsView",
  "nameKey": "Portals.InsightsTab",
  "iconName": "BarChartIcon",
  "href": "/insights/dashboard",
  "themeType": "blue",
  "URLAllowList": ["/insights/*", "/api/insights/*"],
  "configurationSettings": {
    "configurable": true,
    "defaultEnabledState": true,
    "tabTitleKey": "InsightsTabTitle",
    "tabDescriptionKey": "InsightsTabDescription"
  }
}

Example: Configurable Content Tab

Some content tabs can be made configurable, allowing end-users to enable or disable them. Here's an example:

{
  "type": "content",
  "id": "ReportsView",
  "nameKey": "Portals.ReportsTab",
  "iconName": "DocumentIcon",
  "href": "/reports/builder",
  "themeType": "orange",
  "URLAllowList": ["/reports/*"],
  "configurationSettings": {
    "configurable": true,
    "defaultEnabledState": false,
    "tabTitleKey": "ReportTabTitle",
    "tabDescriptionKey": "ReportTabDescription"
  },
  "accessControls": {
    "features": ["CXLOC.Reports"]
  }
}

---

Custom Block Tab

A customBlockTab displays a Custom Block plugin that you have created. This allows you to include custom UI/UX built with the Custom Block SDK.

Key Properties

Property	Type	Description	Required
type	string	Must be "customBlockTab"	Yes
pluginId	string	Unique ID of the Custom Block plugin to display	Yes
nameKey	string	Translation key for the tab name in the side navigation	Yes
iconName	string	Icon name from the available Tab Icons	Yes
themeType	string	Theme color when tab is active	Yes
order	number	Display order of the tab in the side navigation	No
accessControls	object	Permissions required to view this tab	No

Example: Custom Block Tab with Recognition Plugin

{
  "type": "customBlockTab",
  "pluginId": "PLUG_06aba159-c69d-449c-b78f-22d1c70fdf07",
  "nameKey": "Portals.RecognitionTab",
  "iconName": "LightBulbIcon",
  "themeType": "green",
  "order": 200,
  "accessControls": {
    "features": ["CXLOC.Milestones"]
  }
}

Example: Custom Block Tab with Analytics Plugin

{
  "type": "customBlockTab",
  "pluginId": "PLUG_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "nameKey": "Portals.AnalyticsTab",
  "iconName": "ChartIcon",
  "themeType": "blue",
  "order": 150
}

Example: Custom Block Tab with Requirements

{
  "type": "customBlockTab",
  "pluginId": "PLUG_xyz123-abc456-def789",
  "nameKey": "Portals.AdminToolsTab",
  "iconName": "SettingsIcon",
  "themeType": "red",
  "accessControls": {
    "BrandPermissions": ["Brand.Administration"]
  }
}

---

Multi-Page Dashboard Tab

A multiPageDashboardTab displays a specific page from a multi-page Qualtrics dashboard.

Key Properties

Property	Type	Description	Required
type	string	Must be "multiPageDashboardTab"	Yes
id	string	Unique tab identifier (human-readable recommended)	Yes
nameKey	string	Translation key for the tab name in the side navigation	Yes
iconName	string	Icon name from the available Tab Icons	Yes
themeType	string	Theme color when tab is active	Yes
order	number	Display order of the tab in the side navigation	No
accessControls	object	Permissions required to view this tab	No
configurationSettings	object	Settings for whether users can customize this tab	No

Example: Multi-Page Dashboard Tab

{
  "type": "multiPageDashboardTab",
  "id": "PerformanceDashboard",
  "nameKey": "Portals.PerformanceTab",
  "iconName": "LineChartIcon",
  "themeType": "purple",
  "order": 100
}

Example: Configurable Multi-Page Dashboard Tab

{
  "type": "multiPageDashboardTab",
  "id": "SurveyMetricsView",
  "nameKey": "Portals.SurveyMetricsTab",
  "iconName": "DataIcon",
  "themeType": "blue",
  "configurationSettings": {
    "configurable": true,
    "defaultEnabledState": true,
    "tabTitleKey": "SurveyMetricsTitle",
    "tabDescriptionKey": "SurveyMetricsDescription"
  },
  "accessControls": {
    "features": ["CXLOC.Surveys"]
  }
}

---

Complete Example: Purpose-built App with Multiple Tab Types

Here's a complete example of a Purpose-built App configuration that includes all three tab types:

{
  "id": "PLUG_12345678-1234-5678-1234-567812345678",
  "type": "purpose_built_app",
  "metadata": {
    "nameKey": "MyApp.AppName",
    "descriptionKey": "MyApp.AppDescription",
    "tags": ["purposeBuiltApp"],
    "type": "purposeBuiltApp",
    "portalType": "INTERNAL",
    "tabs": [
      {
        "type": "content",
        "id": "TicketsView",
        "nameKey": "MyApp.TicketsTab",
        "iconName": "Tickets",
        "href": "/tickets/app",
        "themeType": "green",
        "order": 100,
        "URLAllowList": ["/tickets/app*"],
        "accessControls": {
          "AccountPermissions": ["AccountPermissions.useTickets"]
        }
      },
      {
        "type": "customBlockTab",
        "pluginId": "PLUG_06aba159-c69d-449c-b78f-22d1c70fdf07",
        "nameKey": "MyApp.RecognitionTab",
        "iconName": "LightBulbIcon",
        "themeType": "green",
        "order": 200,
        "accessControls": {
          "features": ["CXLOC.Milestones"]
        }
      },
      {
        "type": "multiPageDashboardTab",
        "id": "PerformanceDashboard",
        "nameKey": "MyApp.PerformanceTab",
        "iconName": "BarChartIcon",
        "themeType": "blue",
        "order": 300
      }
    ]
  }
}

---

Tab Configuration Best Practices

1. Use Descriptive IDs and Translation Keys

Use clear IDs for content and multiPageDashboardTab tabs, and clear translation keys for all tab names:

{
  "id": "TicketsView",
  "nameKey": "Portals.TicketsTab"
}

2. Set Appropriate Icons

Select icons that clearly represent the tab's content. Common icon options include:

• Tickets - For ticket/support related content
• BarChartIcon or LineChartIcon - For analytics/dashboards
• DocumentIcon - For reports or documents
• SettingsIcon - For configuration/settings
• LightBulbIcon - For insights or custom content
• DataIcon - For data views

3. Use URL Allow Lists

For content tabs, always define URLAllowList to restrict which URLs users can navigate to:

{
  "URLAllowList": ["/tickets/app*", "/api/tickets/*"]
}

4. Configure Permissions Appropriately

Use accessControls to restrict tab visibility based on user permissions or account features:

{
  "accessControls": {
    "AccountPermissions": ["AccountPermissions.useTickets"],
    "features": ["CXLOC.Reports"]
  }
}

5. Make Tabs Configurable When Appropriate

Allow end-users to enable/disable optional tabs:

{
  "configurationSettings": {
    "configurable": true,
    "defaultEnabledState": false,
    "tabTitleKey": "CustomTabTitle",
    "tabDescriptionKey": "CustomTabDescription"
  }
}

---

Troubleshooting

Tab Not Appearing

• Verify the nameKey translation key exists in your translation files
• Check that pluginId (for Custom Block tabs) references a valid plugin
• Ensure user has required permissions specified in accessControls

Content Not Loading

• For content tabs, verify the URL in href is accessible
• Ensure the URL matches patterns in URLAllowList
• Verify the domain is included in the app's validDomains configuration

Custom Block Plugin Not Rendering

• Ensure the plugin ID exists and has been deployed
• Verify the plugin has the purposeBuiltApp tag in its config
• Check that all plugin dependencies are installed

---

Related Resources

• Purpose-built App API Reference
• Purpose-built App Deep Dive
• Purpose-built App Quickstart
• Custom Block Plugins
• Tab Icons Reference