UiWidgetBundle (Beta)

Note

This feature is a beta service that is subject to the Beta Services Terms at Agreements - Salesforce.com or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the Product Terms Directory. Use of this pilot or beta service is at the Customer's sole discretion.

Important

Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

Parent Type

This type extends the Metadata metadata type and inherits its fullName field.

File Structure and Directory Location

UiWidgetBundle components are stored in the uiWidgets folder.

Here’s an example of the UiWidgetBundle structure.

+--myMetadataPackage
    +--uiWidgets (1)
        +--WIDGET_NAME (2)
		+--WIDGET_NAME.json (3)
		+--WIDGET_NAME.uiwidget-meta.xml(4)
		+--schema.json (5)

The bundle includes these resources.

The uiWidgets folder (1) contains a folder for each created widget in the format {widgetName} (2).
Each widget folder contains a {widgetName}.json file (3) that defines the JSON UI composition structure for the widget, specifying the component layout, nesting, and data bindings.
Each widget folder also contains a {widgetName}.uiwidget-meta.xml file (4) that defines the widget type.
Finally, an optional schema.json file (5) defines the attribute contract—the attributes and their associated Lightning types the widget accepts.

Version

UiWidgetBundle components are available in API version 67.0 and later.

Fields

Field Name	Description
description	Field Type string Description Required. Describes the widget.
masterLabel	Field Type string Description Required. Represents the name of a widget bundle which is defined when the UiWidgetBundle is created.
widgetType	Field Type string Description Required. Represents the widget type. The only allowed value is `JSON`.

Declarative Metadata Sample Definition

This package.xml file retrieves all the UiWidgetBundle components in an org.

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>*</members>
        <name>UiWidgetBundle</name>
    </types>
    <version>67.0</version>
</Package>

In the retrieved .zip file, each widget is nested under a uiWidgets folder.

This example shows the directory structure in the .zip file of a widget named hotelCard:

+--uiWidgets
        +--hotelCard
            +--schema.json
            +--hotelCard.json
            +--hotelCard.uiwidget-meta.xml

Here are the contents of the files in the hotelCard directory. This sample code shows the contents of the schema.json file.

{
  "title": "Hotel Card Widget",
  "description": "Displays hotel information as a visual card",
  "type": "object",
  "properties": {
    "attributes": {
      "lightning:type": "lightning__objectType",
      "properties": {
        "title": {
          "title": "Hotel Name",
          "description": "Primary heading displayed at the top",
          "lightning:type": "lightning__textType"
        },
        "imageUrl": {
          "title": "Image URL",
          "description": "URL of the hotel image",
          "lightning:type": "lightning__urlType"
        },
        "price": {
          "title": "Price Per Night",
          "description": "Nightly rate displayed as currency",
          "lightning:type": "lightning__numberType"
        },
        "description": {
          "title": "Description",
          "description": "Short description of the hotel",
          "lightning:type": "lightning__textType"
        }
      }
    }
  }
}

Contents of the hotelCard.json file.

{
  "type": "lightning__agentforceWidget",
  "contentBody": {
    "widgetBody": {
      "definition": "tile/widget",
      "children": [
        {
          "definition": "tile/card",
          "attributes": {
            "padding": "lg",
            "variant": "default",
            "maxWidth": "full"
          },
          "children": [
            {
              "definition": "tile/image",
              "attributes": {
                "src": "{!$attrs.imageUrl}",
                "alt": "{!$attrs.title}"
              }
            },
            {
              "definition": "tile/text",
              "attributes": {
                "text": "{!$attrs.title}",
                "variant": "h3",
                "weight": "semibold"
              }
            },
            {
              "definition": "tile/text",
              "attributes": {
                "text": "{!$attrs.price}",
                "variant": "body",
                "weight": "medium"
              }
            },
            {
              "definition": "tile/text",
              "attributes": {
                "text": "{!$attrs.description}",
                "variant": "body"
              }
            }
          ]
        }
      ]
    }
  }
}

Contents of the hotelCard.uiwidget-meta.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<UiWidgetBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>Hotel Card</masterLabel>
    <description>Displays hotel information as a visual card.</description>
    <widgetType>JSON</widgetType>
</UiWidgetBundle>

Wildcard Support in the Manifest File

This metadata type supports the wildcard character * (asterisk) in the package.xml manifest file. For information about using the manifest file, see Deploying and Retrieving Metadata with the Zip File.