# Widgets

## Overview

The BlueFletch Launcher configuration allows placement of different kinds of widgets on the home screen for the user. Like applications and shortcuts, these can configured to be role-based, such that front-line workers may see widgets related to pending or pickup orders, while managers may see high level metrics about the current store operations.

Unlike other Launchers, the BlueFletch Launcher allows the administrator to pre-define the widget configuration and not have to rely on the user to place the widgets themselves.

## Configuring a Widget

Widgets are just another layout object to be included in the `layouts` section of the launcher configuration file. Each widget layout object consists of the following:

<table><thead><tr><th width="255">Field</th><th>Description</th></tr></thead><tbody><tr><td>widgetId</td><td><strong>string</strong> a unique string identifier for this widget. This must be unique across all widgets in the configuration file, and is also used to send data updates to a widget.</td></tr><tr><td>widgetType</td><td><strong>string</strong> describes the type of widget to render. Current available values are: <code>app</code>, <code>list</code>, <code>text</code>, <code>login</code>, <code>session</code>, <code>toolbar</code>, <code>bannerLarge</code>, <code>webview</code>, <code>search</code>, <code>space</code>, <code>quickStart</code> </td></tr><tr><td>columnSpan</td><td><strong>number</strong> the number of columns this widget will occupy. This is based on the number of columns specified in the <code>layoutSettings</code> configuration.</td></tr><tr><td>rowSpan</td><td><strong>number</strong> the number of rows this widget will occupy. Each row is one icon high.</td></tr><tr><td>widgetParams</td><td><strong>object</strong> this is a JSON object that contains additional parameters to configure the widget. This object changes based on the <code>widgetType</code> specified above. Available starting in Launcher version 3.22.x.</td></tr></tbody></table>

{% hint style="info" %}
`widgetParams` values also support configuration and session replacement values.
{% endhint %}

Launcher has the ability to host different kinds of widgets. The Launcher can host native application widgets (e.g. widgets that are built into an application). Launcher has other pre-built widgets designed specifically for shared device use.

The following widget types are available:

<table><thead><tr><th width="288.328125">widgetType</th><th>Example</th></tr></thead><tbody><tr><td>"app"</td><td>A placeholder for automatically placing and rendering <a href="#native-application-widgets">native application widgets</a>.</td></tr><tr><td>"bannerLarge"</td><td>A large banner typically used as the <a href="#open-zone-banner-widget">Open Zone header</a>,.</td></tr><tr><td>"session"</td><td>A smaller banner type widget typically used for an <a href="#session-widget">authenticated session</a>.</td></tr><tr><td>"webview"</td><td>A widget that can be used to display HTML content or a website using the Android system <a href="#webview-widget">webview</a>.</td></tr><tr><td>"space"</td><td>A widget that can be used to add blank grid <a href="#space-widget">spaces</a> into the workspace.</td></tr><tr><td>"search"</td><td>A search toolbar widget that directly launches into the Launcher's app / shortcut <a href="#search-widget">search function</a>.</td></tr><tr><td>"text"</td><td>A simple widget that displays a <a href="#text-widget">title text and value</a>.</td></tr><tr><td>"flashlight"</td><td>A widget that can be placed on the workspace to allow the User to toggle the device flashlight on or off.</td></tr></tbody></table>

## Native Application Widgets

These are widgets built into applications that follow the App Widget SDK guidelines from Android as defined in <https://developer.android.com/develop/ui/views/appwidgets/overview>.

<figure><img src="https://799338798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSxhNrDkmDAkv7QEWfOIh%2Fuploads%2FQ21rGFJfgheAJ81OJw94%2FScreen%20Shot%202023-08-17%20at%204.00.17%20PM.png?alt=media&#x26;token=aa2efff4-836d-44d3-9cc7-65c2e007b323" alt="" width="375"><figcaption><p>Launcher displaying the Digital Clock Widget</p></figcaption></figure>

To configure an application widget, use the `widgetType = app` and define the `widgetParams` as follows:

```json

{
    "widgetId" : "digital-clock",
    "widgetType" : "app",
    "columnSpan" : 3,
    "rowSpan" : 1,
    "widgetParams" : {
        "package" : "com.google.android.deskclock"
    }
}
```

The `widgetParams` object for type `app` consists of the following:

<table><thead><tr><th width="296">Field</th><th>Description</th></tr></thead><tbody><tr><td>package</td><td><strong>string</strong> the package name of the application containing the widget.</td></tr><tr><td>componentName</td><td><strong>string (optional)</strong> the full component name of the widget inside the application. This is not required if there is only one widget in the application. If an application has multiple available widgets, specify the full component name here, otherwise the Launcher will use the first enumerated widget.</td></tr></tbody></table>

Below is an example of the clock widget, specifying the analog clock widget provider (instead of the digital clock):

```json
{
    "widgetId" : "analog-clock",
    "widgetType" : "app",
    "columnSpan" : 2,
    "rowSpan" : 2,
    "widgetParams" : {
        "package" : "com.google.android.deskclock",
        "componentName" : "com.google.android.alarmclock.AnalogAppWidgetProvider"
    }
}
```

## Custom Launcher Widgets

These are widgets that are built into the Launcher to allow you to take advantage of widgets without requiring additional native development of widgets into your applications, with several that can be updated by a simple broadcast intent. The following custom Launcher widgets are currently available:

### Text Widget

This widget can be used to display text or a simple value/text combination or an icon/text combination, and can run a custom intent when the widget is tapped.

<figure><img src="https://799338798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSxhNrDkmDAkv7QEWfOIh%2Fuploads%2FU3iBxGd4fbTI0VxzRygv%2FScreen%20Shot%202023-08-17%20at%204.11.13%20PM.png?alt=media&#x26;token=e9ca096f-afcd-4836-935a-21ad0b15886c" alt="" width="375"><figcaption><p>Launcher displaying three Text-type widgets (Pending Orders, For Pickup) and as a Message text.</p></figcaption></figure>

To display a simple text in a widget, specify the title in the widget params:

```json
{
    "widgetId" : "simple-text-1",
    "widgetType" : "text",
    "columnSpan" : 4,
    "rowSpan" : 1,
    "widgetParams" : {
        "defaultTitle" : "Cycle count is due for Aisle 5",
        "onItemClick" : {
            .. Custom Intent Object ..
        }
    }
}
```

To display a simple value/text in a widget, specify the value in the widget params as well as the command to launch the BOPIS application when tapped:

```json
{
    "widgetId" : "simple-text-1",
    "widgetType" : "text",
    "columnSpan" : 2,
    "rowSpan" : 1,
    "widgetParams" : {
        "defaultValue": "23"
        "defaultTitle" : "Pending Orders",
        "onItemClick" : {
            "typeIntent" : "a",
            "package" : "com.mycompany.fulfillmentapp"
        }
    }
}
```

The `widgetParams` object for type `text` consists of the following:

<table><thead><tr><th width="296">Field</th><th>Description</th></tr></thead><tbody><tr><td>defaultTitle</td><td><strong>string</strong> The text to display at the bottom of the widget.</td></tr><tr><td>defaultValue</td><td><strong>string (optional)</strong> If specified, will display the value in large font above the widget. if not specified or blank, the value will be hidden.</td></tr><tr><td>icon</td><td><strong>string (optional)</strong> URL, file path or asset name of the icon image to display. If specified will display the icon above the title. If not specified or blank, the icon will be hidden.</td></tr><tr><td>iconSize</td><td><strong>string (optional)</strong> Size in dp for the icon, if specified. Note that the icon shall always be rendered in a square container.</td></tr><tr><td>onItemClick</td><td><strong>object</strong> A custom intent object that will be triggered when the user taps on the widget. For more information on a configuring a custom intent, refer to this link.</td></tr><tr><td>defaultColor</td><td><strong>string</strong> The font color, in hex code format, of the widget's title and value text. Default is white (#FFFFFF)</td></tr><tr><td>backgroundColor</td><td><strong>string</strong> The color, in hex code format, of the widget's translucent background.</td></tr></tbody></table>

{% hint style="info" %}
Note that you can use replacement values for each of the widget params.
{% endhint %}

### Webview Widget

This widget allows you to display a webpage directly on the Launcher home screen.

<figure><img src="https://799338798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSxhNrDkmDAkv7QEWfOIh%2Fuploads%2FHcsnhXWXy2NUxPrgdpsS%2Fimage.png?alt=media&#x26;token=104c714c-f622-472a-8271-df795cac5a23" alt="" width="375"><figcaption><p>A webview type widget displaying the BlueFletch about page.</p></figcaption></figure>

You can display a webview widget using the configuration below, by specifying the type `webview`

```json
{
    "widgetId" : "web-widget",
    "widgetType" : "webview",
    "columnSpan" : 4,
    "rowSpan" : 3,
    "widgetParams" : {
        "url" : "https://bluefletch.com",
        "allowInteraction" : true,
        "onItemClick" : {
            "typeIntent" : "a",
            "package" : "com.mycompany.fulfillmentapp"
        }
    }
}
```

The `widgetParams` object for type `webview` consists of the following:

<table><thead><tr><th width="296">Field</th><th>Description</th></tr></thead><tbody><tr><td>url</td><td><strong>string</strong> The URL of the webpage to be displayed in the webview</td></tr><tr><td>allowInteraction</td><td><strong>boolean</strong> If set to true, will allow the user to interact with the page like a normal browser, e.g. scroll and tap within the page. Default is <code>false</code>.</td></tr><tr><td>onItemClick</td><td><p><strong>object</strong> A custom intent object that will be triggered when the user taps on the widget. If using this function, <code>allowInteractions</code> must be set to false.</p><p>For more information on a configuring a custom intent, refer to this link.</p></td></tr></tbody></table>

#### Widget Actions in Webview

Using Android deeplink URIs, you can have an element in your HTML widget to open a native application on the device.   The webview widget exposes a Javascript interface `WidgetAction` that you can call from inside your page script.   In your webpage javascript:

```html
<script>
    function openNativeApp() {
        // Try to call WidgetAction interface if available
        if (typeof WidgetAction !== 'undefined' && WidgetAction.openUri) {
            WidgetAction.openUri('com.acme.inventory://todos');
        } 
    }
</script>
```

### Open Zone Banner Widget

This widget replaces the current fixed header with a widget and comes standard with your default Launcher installation. Beginning Launcher 3.22.x, you can now specify a widget as the header for the open zone by defining a widget within the `"header"` array at the base level of the launcher configuration.

<figure><img src="https://799338798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSxhNrDkmDAkv7QEWfOIh%2Fuploads%2FRzbuuIDkRlkAG3DuEJSs%2FScreen%20Shot%202023-08-17%20at%2012.36.55%20AM.png?alt=media&#x26;token=53c782ba-247a-4be5-bf55-78e823dbaa7a" alt="" width="375"><figcaption><p>Large Banner widget for Open Zone</p></figcaption></figure>

This is configured in Launcher using the following widget configuration, which includes criteria to check that there is no user session:

```json
"header": [
   {
      "id": "default_openzone",
      "layout": {
         "widgetId": "openzone-banner",
         "widgetType": "bannerLarge",
         "columnSpan": 1,
         "rowSpan": 1,
         "widgetParams": {
             "bannerText" : "${launcherState.formattedText}",
             "bannerImage" : "${launcherState.theme.logo}",
             "buttonColor" : "${launcherState.theme.accentColor}",
             "enterButtonText": "Touch to Login",
             "isAuthPresent" : "${launcherState.isAuthPresent}"
         },
         "criteria_OR": [
           {
             "field": "_${session.userId}",
             "pattern": "^_$"
           }
         ]
      }
   }
   ...
]
```

The `widgetParams` object for type `bannerLarge` consists of the following:

<table><thead><tr><th width="296">Field</th><th>Description</th></tr></thead><tbody><tr><td>bannerImage</td><td><strong>string</strong> A URL, filepath or asset for the image logo</td></tr><tr><td>bannerText</td><td><strong>string (optional)</strong> The text to display between the logo and the Login button. You can use replacement variables here to be able to display dynamic information like site, serial number, etc.</td></tr><tr><td>useDarkText</td><td><strong>boolean</strong> If set to <code>true</code>, will render the bannerText in dark text to contrast a white wallpaper, otherwise will render the bannerText in light text.</td></tr><tr><td>buttonColor</td><td><strong>string</strong> Hexidecimal representation of a color for the button. The button text will automatically change color based on the appropriate contrast level.</td></tr><tr><td>backgroundColor</td><td><strong>string</strong> Hexadecimal representation of the background. To change the background opacity, add the alpha value as the first two values in the hex string, e.g. #50FFFFFF</td></tr><tr><td>enterButtonText</td><td><strong>string</strong> The custom text to display on the Login button in the banner. By default, the text is LOGIN. Available on <code>bannerLarge</code> widget type.</td></tr><tr><td>isAuthPresent</td><td><strong>boolean</strong> If <code>true</code>, the login button is present in the header; if <code>false</code>, login button is hidden. By using a launcherState variable, Launcher will dynamically set the boolean value based on installation status of the Auth app. Introduced in Launcher version 3.24.11.</td></tr></tbody></table>

### Session Widget

The "session" widget can display your current session information, along with a button to be able to log out or exit your current session. You are able to specify one headline and two additional sub-text under the headline.

<figure><img src="https://799338798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSxhNrDkmDAkv7QEWfOIh%2Fuploads%2FsmTwbSLS2PPWNm0YVryL%2Fimage.png?alt=media&#x26;token=06107be6-8b6f-42d3-a4a2-3ec3186d7f1e" alt="" width="375"><figcaption><p>Session Widget as Header</p></figcaption></figure>

This widget can be configured in Launcher using criteria to check for a current user session, and is represented by the following widget configuration:

```json
"header": [
    ...
    {
        "id": "default_authorized",
        "layout": {
              "widgetId": "session-banner",
              "widgetType": "session",
              "columnSpan": 1,
              "rowSpan": 1,
              "widgetParams": {
                  "heading" : "${session.userName}",
                  "subtitle1" : "${launcherState.formattedText}",
                  "subtitle2" : "",
                  "exitButtonText" : "${res.launcher_base_launcher_button_logout}",
                  "exitButtonColor" : "${launcherState.theme.accentColor}"
              },
              "criteria_OR": [
                {
                  "field": "_${session.userId}",
                  "pattern": "^_.+$"
                }
              ]
         }
     }
 ] 
```

{% hint style="info" %}
Learn more about the Criteria functionality on this [page](/bluefletch-enterprise/product-guides/bluefletch-launcher/configurable-layouts/criteria.md).
{% endhint %}

The `widgetParams` object for type `session` consists of the following:

| Field           | Description                                                                                                                                               |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| heading         | **string** The custom text to display in the banner. Usually set as the session username.                                                                 |
| subtitle1       | **string** Custom text 1 to display in the banner.                                                                                                        |
| subtitle2       | **string** Custom text 2 to display in the banner.                                                                                                        |
| exitButtonText  | **string** The custom text to display on the Login button in the banner. By default, the text is LOGOUT. Available on `session` widget type.              |
| exitButtonColor | **string** Hexidecimal representation of a color for the button. The button text will automatically change color based on the appropriate contrast level. |

### Search Widget

The "search" widget can be configured in Launcher to provide device Search capability on the home screen.

```json
"footer" : [
  {
    "id" : "default_openzone",
    "layout" : {
      "widgetId": "scan-or-search-01",
      "widgetType": "search",
      "columnSpan": 1,
      "rowSpan": 2
   }
]
```

{% hint style="info" %}
Similar to the Session Widget, a criteria can likewise be applied in the Footer section to conditionally display the Search Widget. Available in Launcher 4.
{% endhint %}

### Space Widget

The "space" widget type can be used to display an empty space the size of one or more application icons on a layout. This is useful for creating a separation between groups of apps to differentiate their purposes (for example, a delineation between inventory apps and point of sale apps). In particular, if enough icon fields are taken up by the widget, page break is created between the groups.

<figure><img src="https://799338798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSxhNrDkmDAkv7QEWfOIh%2Fuploads%2FE2d0MeKAXv5asCxmqiZ3%2FScreenshot%202025-07-23%20at%202.26.12%E2%80%AFPM.png?alt=media&#x26;token=5a9cbfcd-51e3-40c7-9cac-b95fa12938a1" alt="" width="375"><figcaption></figcaption></figure>

The dimensions of the widget are defined by `rowSpan` (horizontal width) and `columnSpan` (vertical height). `widgetId` can be any string to descriptively name the widget.

```json
{
    "widgetId": "space_1x1",
    "widgetType": "space",
    "rowSpan": 1,
    "columnSpan": 1
}
```

{% hint style="info" %}
The widget type "space" is introduced in Launcher version 3.26.24.
{% endhint %}

### Quick Start Bar Widget <a href="#configuring-the-quick-start-applications-folder-3" id="configuring-the-quick-start-applications-folder-3"></a>

To configure the quickStart bar as a widget, use the example below as a guide:

```json
{
  "widgetId": "quick-start-001",
  "widgetType": "quickStart",
  "columnSpan": 1,
  "rowSpan": 4,
  "widgetParams": {
    "showLabel": true,
    "applicationList": [
    ...
      {
        "package": "com.bluefletch.ems.web-site.launcher",
        "activity": "SearchActivity",
        "label": "Search"
      },
      {
        "package": "com.bluefletch.web-site.chat"
      },
      {
        "package": "com.bluefletch.ems.web-site.support"
      }
      ...
    ]
  }
}
```

To specify the `quickStart` bar as a footer, use the example below as a guide:

```json
"footer": [
  ...
  {
    "id" : "default_authorized",
    "layout" : {
      "widgetId": "quick-start-001",
      "widgetType": "quickStart",
      "columnSpan": 1,
      "rowSpan": 4,
      "widgetParams": {
        "showLabel": true,
        "applicationList": [
        ...
          {
            "package": "com.bluefletch.ems.web-site.launcher",
            "activity": "SearchActivity",
            "label": "Search"
          },
          {
            "package": "com.bluefletch.web-site.chat"
          },
          {
            "package": "com.bluefletch.ems.web-site.support"
          }
          ...
        ]
      }
    },
    "criteria_OR": [
        {
          "field": "_${session.userId}",
          "pattern": "^_.+$"
        }
    ]
  }
  ...
]
```

{% hint style="info" %}
Quick Start Bar Widget was introduced in Launcher 4.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bluefletch.com/bluefletch-enterprise/product-guides/bluefletch-launcher/configurable-layouts/widgets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.