Widgets

📘

Getting started

To get started, see widgets in the app components guide.

Schemas

WidgetMetadata

An object containing information about the widget. See get widget metadata.

PropertyTypeDescription
metadata (required)objectThe metadata (i.e., underlying definition) of a widget. metadata must exist alongside a template, and its schema must be specific to the value of that template.
» errorstringThe error that should be displayed to the user.
» fields (required)arrayA list of fields showing data from external resources (i.e., an array of WidgetField objects). A widget must contain at least 1 field and no more than 5 fields.

Valid object schemas:
- WidgetField-DatetimeWithIcon
- WidgetField-Pill
- WidgetField-TextWithIcon
» footer (required)objectContains the information to display a footer on the widget.

Valid schemas:
- WidgetFooter-Created
- WidgetFooter-CustomText
- WidgetFooter-Updated
» num_commentsintegerThe number of comments to display on the lower right corner of the widget. If not provided, no comment count will be shown
» subicon_urlstringThe URL of the subicon next to the subtitle. If not provided, no icon will be shown.
» subtitlestringThe text to show under the title of the widget, next to "Open in {App Name}". If not provided, the resource_name from the app definition will be used as default.
» title (required)stringThe text to show in the title of the widget. Max length of 200 characters.
template (required)stringThe interface name and version of a distinct widget UI layout. A template is directly associated with a particular metadata schema.
{
  "metadata": {
    "error": "The resource cannot be accessed",
    "fields": [],
    "footer": {},
    "num_comments": 2,
    "subicon_url": "https://example-icon.png",
    "subtitle": "Custom App Story · Open in Custom App",
    "title": "Status"
  },
  "template": "summary_with_details_v0"
}

WidgetField-DatetimeWithIcon

A widget field that displays a timestamp and an optional icon.

PropertyTypeDescription
datetimestringThe time (in ISO 8601 date format) to display next to the icon.
icon_urlstringOptional. The URL of the icon to display next to the time.
name (required)stringThe text (i.e., label) to show in the title of the field. Limit 40 characters.
type (required)stringThe type of widget field.
{
  "datetime": "2012-02-22T02:06:58.147Z",
  "icon_url": "https://example-icon.png",
  "name": "Status",
  "type": "datetime_with_icon"
}

WidgetField-Pill

A widget field that displays custom text in a colored "pill" format.

PropertyTypeDescription
color (required)stringThe color of the pill.
name (required)stringThe text (i.e., label) to show in the title of the field. Limit 40 characters.
text (required)stringThe text to show in the field. Limit 40 characters.
type (required)stringThe type of widget field.
{
  "color": "cool-gray",
  "name": "Status",
  "text": "In Progress",
  "type": "pill"
}

WidgetField-TextWithIcon

A widget field that displays custom text with an optional icon.

PropertyTypeDescription
icon_urlstringOptional. The URL of the icon to display next to the text.
name (required)stringThe text (i.e., label) to show in the title of the field. Limit 40 characters.
text (required)stringThe text to show in the field. Limit 40 characters.
type (required)stringThe type of widget field.
{
  "icon_url": "https://example-icon.png",
  "name": "Status",
  "text": "In Progress",
  "type": "text_with_icon"
}

WidgetFooter-Created

A widget footer that displays the timestamp of the resource's creation time.

PropertyTypeDescription
created_at (required)stringThe time (in ISO 8601 date format) to show in the footer.
footer_type (required)stringThe type of widget footer.
{
  "created_at": "2012-02-22T02:06:58.147Z",
  "footer_type": "created"
}

WidgetFooter-CustomText

A widget footer that displays custom text and an optional icon.

PropertyTypeDescription
footer_type (required)stringThe text to show in the footer.
icon_urlstringOptional. The icon to show in the footer next to the text. If not provided, no icon will be shown.
text (required)stringThe text to show in the footer.
{
  "footer_type": "custom_text",
  "icon_url": "https://example-icon.png",
  "text": "This is a custom footer message"
}

WidgetFooter-Updated

A widget footer that displays the timestamp of the resource's last updated time.

PropertyTypeDescription
footer_type (required)stringThe type of widget footer.
last_updated_at (required)stringThe time (in ISO 8601 date format) to show in the footer.
{
  "footer_type": "updated",
  "last_updated_at": "2012-02-22T02:06:58.147Z"
}

Error schemas

BadRequest

An error response object indicating a bad request (i.e., a status code of 400).

PropertyTypeDescription
dataobjectAn object containing an error string to display to the user.
» errorstringThe error to display.
{
  "data": {
    "error": "Illegal or malformed request."
  }
}

Forbidden

An error response object indicating a forbidden request (i.e., a status code of 403).

PropertyTypeDescription
dataobjectAn object containing an error string to display to the user.
» errorstringThe error to display.
{
  "data": {
    "error": "Access forbidden."
  }
}

InternalServerError

An error response object indicating a request that could not be found (i.e., a status code of 500).

PropertyTypeDescription
dataobjectAn object containing an error string to display to the user.
» errorstringThe error to display.
{
  "data": {
    "error": "Internal server error."
  }
}

NotFound

An error response object indicating a request that could not be found (i.e., a status code of 404).

PropertyTypeDescription
dataobjectAn object containing an error string to display to the user.
» errorstringThe error to display.
{
  "data": {
    "error": "Not found."
  }
}

Unauthorized

An error response object indicating a unauthorized request (i.e., a status code of 401).

PropertyTypeDescription
dataobjectAn object containing an error string to display to the user.
» errorstringThe error to display.
{
  "data": {
    "error": "Authorization required."
  }
}