# Widget Configuration

For each widget, you must specify the name, and the size and position of the widget in the dashboard grid.

The following table describes the parameters for all widgets. All options are required unless otherwise specified.

Property | Description | Type
--- | --- | ---
`name` | The name of the widget. | String
`type` | The type of widget. See the individual widget sections for the value to use. | String Enum
`x` | The position of the left side of the widget, from the left side of the dashboard (the left side is `0`). Widgets align to grid squares. You must set the position so that the whole widget appears within the dashboard width. | Integer
`y` | The position of the top of the widget, from the top of the dashboard (the top is `0`). Widgets align to grid squares. You must set the position so that the whole widget appears within the dashboard height. | Integer
`width` | The width of the widget, in grid squares. This value must be less than the total width of the dashboard, and less than the combined width of the widgets on the same row of the dashboard. | Integer
`height` | The height of the widget, in grid squares. This value must be less than the total height of the dashboard, and less than the combined height of the widgets in the same column in the dashboard. | Integer
`cssClass` | Optional. A CSS class to use for the widget. | String
`displayWidgetName` | Optional. A string that determines whether to display the name of the widget. Use one of the following options: always. Always display the name for this widget, if it has one. onhover. Display the name only when a user mouses over the widget. never. Never display the name, even if it has one in the widget configuration. This option overrides the `displayWidgetNames` option in the dashboard configuration, which has a default value of never. See Dashboard Configuration. | String Enum

For more information about the dashboard grid, see Dashboard Grid Size.

For widgets that require a saved search, you must also specify the ID and type of the saved search. You add the saved search by using the `datasource` property, which is a JSON object with the following properties:

`source` | The type of data source to use for the widget. For a saved search, set this option to `SavedSearch`.
`config` | A JSON object that defines the configuration for the data source. For the `SavedSearch` source, this object has the following required subproperties: `id` (string). The ID of the saved search to use for this widget. You find the ID by opening the saved search tab in the Find user interface, and checking the URL. In the URL, the saved search type and ID appear after `tab/`, as `QUERY:ID` or `SNAPSHOT:ID`, where ID is a number. `type` (string enum). The type of saved search: QUERY or SNAPSHOT.

The following example shows the basic widget configuration.

    "widgets": [
       {
          "name": "TopicMap",
          "type": "TopicMapWidget",
          "x": 1,
          "y": 1,
          "width": 2,
          "height": 2,
          "datasource": {
             "source": "SavedSearch",
             "config": {
                "type": "QUERY",
                "id": "1234"
             }
          },
          "widgetSettings": {
             "maxResults": 1000
          }
       }
    ]

Each widget has some specific configuration details, which you specify in the `widgetSettings` object in the dashboard configuration. The available parameters are described in the following sections.

## Topic Map Widget

For the Topic Map widget, set `type` to TopicMapWidget.

This widget type requires a saved search. You must set the `source` property to `SavedSearch` in the widget configuration.

The following table describes the options that you can use in the `widgetSettings` object.

Property | Required | Description | Default
--- | --- | --- | ---
`maxResults` | No | The maximum number of results to retrieve from the saved search to form the topic map. Requesting more results generally gives a more accurate topic map, but the widget might load and refresh more slowly. | 300

Example widget configuration:

    {
       "name": "TopicMap",
       "type": "TopicMapWidget",
       "x": 0,
       "y": 0,
       "width": 1,
       "height": 1,
       "datasource": {
          "source": "SavedSearch",
          "config": {
             "type": "QUERY",
             "id": "1234"
          }
       },
       "widgetSettings": {
          "maxResults": 1000
       }
    }

## Results List Widget

For the Results List widget, set `type` to ResultsListWidget.

This widget type requires a saved search. You must set the `source` property to `SavedSearch` in the widget configuration.

The following table describes the options that you can use in the `widgetSettings` object.

Property | Required | Type | Description | Default
--- | --- | --- | --- | ---
`columnLayout` | No | Boolean | Set to true to display results in columns instead of rows. | false
`maxResults` | No | Integer | The maximum number of results to include in the results list. | 6
`sort` | No | String enum | The sort option to use to order the results. Micro Focus recommends that you use only date and relevance, which match the options available in the Find user interface. However, you can use any sort method that is supported by the IDOL Content component. In this case, the result order might be different to the rest of your user interface. For details of the available sort options, refer to the IDOL Content Component Reference. | relevance

Example widget configuration:

    {
       "name": "List",
       "type": "ResultsListWidget",
       "x": 1,
       "y": 1,
       "width": 2,
       "height": 2,
       "datasource": {
          "source": "SavedSearch",
          "config": {
             "type": "QUERY",
             "id": "1234"
          }
       },
       "widgetSettings": {
          "maxResults": 10
       }
    }

## Sunburst Widget

For the Sunburst widget, set `type` to SunburstWidget.

This widget type requires a saved search. You must set the `source` property to `SavedSearch` in the widget configuration.

The following table describes the options that you can use in the `widgetSettings` object.

Property | Required | Type | Description | Default
--- | --- | --- | --- | ---
`firstField` | Yes | String | The name of the field to display on the inner ring. |
`maxLegendEntries` | No | Integer | The maximum number of values to display in the legend, for each tier. If the search returns more than the specified number of values for the field, colors and legend entries are assigned to the values with the largest contribution, and the remaining values are displayed in white. | 5
`secondField` | No | String | The name of the field to display on the outer ring. If you do not set this property, the widget displays only a single ring. |

Example widget configuration:

    {
       "name": "Sunburst",
       "type": "SunburstWidget",
       "x": 2,
       "y": 2,
       "width": 1,
       "height": 1,
       "datasource": {
          "source": "SavedSearch",
          "config": {
             "type": "QUERY",
             "id": "1234"
          }
       },
       "widgetSettings": {
          "firstField": "category",
          "secondField": "person"
       }
    }

## Trending Widget

For the Trending widget, set `type` to TrendingWidget.

This widget type requires a saved search. You must set the `source` property to `SavedSearch` in the widget configuration.

The following table describes the options that you can use in the `widgetSettings` object.

Property | Required | Type | Description | Default
--- | --- | --- | --- | ---
`parametricField` | Yes | String | The name of the field to display in the trending visualization. |
`dateField` | No | String | The name of the date field to use to find the date associated with particular values in the trending visualization. | `AUTN_DATE`
`numberOfBuckets` | No | Integer | The number of points to include on the trending lines. Each point represents the document rate for a particular time range (bucket). The number of buckets controls how many buckets to split the full time range into. | 20
`maxValues` | No | Integer | The maximum number of top values to display from the specified parametric field. If you define the `values` object for this widget, it overrides the `maxValues` setting. | 10
`maxDate` | No | String | The maximum date to include in the visualization. Specify a date in the format `YYYY-MM-DDT hh:mm:ssZ`. This value becomes the maximum value on the x-axis. By default, the visualizer displays the maximum date that occurs in the documents with the specified parametric field. | unlimited
`minDate` | No | String | The minimum date to include in the visualization. Specify a date in the format `YYYY-MM-DDT hh:mm:ssZ`. This value becomes the minimum value on the x-axis. By default, the visualizer displays the minimum date that occurs in the documents with the specified parametric field. | unlimited
`values` | No | Object | A JSON object that specifies particular values that you want to display in the visualization. If you define values, the visualization includes only the specified values, regardless of `maxValues`. This object contains the following properties: `name` (string). Required. The field value to display in the visualization. `color` (string). Optional. The color to use for the trending line for this field value. You can use the values blue, light-blue, orange, pink, light-pink, green, light-green, red, purple, and yellow. If you do not specify a color, Find assigns colors at random. |

Example widget configuration:

    {
       "name": "Trending",
       "type": "TrendingWidget",
       "x": 0,
       "y": 0,
       "width": 2,
       "height": 2,
       "datasource": {
          "source": "SavedSearch",
          "config": {
             "type": "QUERY",
             "id": "1234"
          }
       },
       "widgetSettings": {
          "parametricField": "OVERALL_VIBE",
          "dateField": "AUTN_DATE",
          "numberOfBuckets": 25,
          "values": [
             {
                "name": "POSITIVE",
                "color": "purple"
             },
             {
                "name": "NEGATIVE",
                "color": "orange"
             }
          ]
       }
    }

## Map Widget

For the Map widget, set `type` to MapWidget.

NOTE: Map widgets display correctly only if you configure the map visualizers. See Configure Map Visualizations.

This widget type requires a saved search. You must set the `source` property to `SavedSearch` in the widget configuration.

The following table describes the options that you can use in the `widgetSettings` object.

Property | Required | Type | Description | Default
--- | --- | --- | --- | ---
`centerCoordinates` | Yes | Object | The coordinates to center the map on. This object has the following properties: `latitude` (number). The latitude coordinate to use as the center of the map. `longitude` (number). The longitude coordinate to use as the center of the map. |
`locationFieldPairs` | Yes | String Array | The names of the configured field pairs to use as the location for the result markers. You find the names to use here in the `displayName` property of the maps section in the `config.json` configuration file. |
`zoomLevel` | Yes | Number | The level of zoom to use for the map. The value that you use for this option depends on your map tile server. |
`clusterMarkers` | No | Boolean | Set to true to cluster the result markers. | false
`disableAutoZoom` | No | Boolean | Set to true if you want the map to continue to show your original coordinates when the search results load. By default, Find modifies the zoom to show all the loaded markers. | false
`maxResults` | No | Integer | The maximum number of search results to display on the map. | 1000

Example widget configuration:

    {
       "name": "Map",
       "type": "MapWidget",
       "x": 1,
       "y": 1,
       "width": 2,
       "height": 2,
       "datasource": {
          "source": "SavedSearch",
          "config": {
             "type": "QUERY",
             "id": "1234"
          }
       },
       "widgetSettings": {
          "maxResults": 10000,
          "locationFieldPairs": ["DefaultLocation", "OtherLocation"],
          "centerCoordinates": {
             "latitude": 51.5,
             "longitude": 0.12
          },
          "zoomLevel": 3,
          "clusterMarkers": true
       }
    }

## Video Panel Widget

For the Video Panel widget, set `type` to VideoWidget.

This widget type requires a saved search. You must set the `source` property to `SavedSearch` in the widget configuration.

The following table describes the options that you can use in the `widgetSettings` object.

Property | Required | Type | Description | Default
--- | --- | --- | --- | ---
`audio` | No | Boolean | Set to true to play the audio for the video. | false
`crossOrigin` | No | String | The CORS settings to use (anonymous or use-credentials). You might need this option to enable Find to export video as an image in a PowerPoint report, if you host videos on a different server to Find. Use this option only if the server you use to host your videos supports CORS headers. You do not need this setting if your video is hosted on the same site as Find (including by reverse-proxy), or if you do not want to export video dashboards. |
`loop` | No | Boolean | Set to false if you do not want to replay the video when it finishes. In this case, the video stops after it reaches the end and does not replay until the widget refreshes. By default, the video loops. | true
`restrictSearch` | No | Boolean | Set to true to restrict the saved search to return only results with the content type field value video. | false
`searchResultNumber` | No | Integer | The number of the result that you want to play (for example, 2 to play the second result in the list). | 1

NOTE: The widget displays a result only if it is type video. To ensure that the results include only videos, set `restrictSearch` to true.

Alternatively, you can set `searchResultNumber` to display a specific video result (for example, if you want to display a particular result from a snapshot saved search).

Example widget configuration:

    {
       "name": "Video Widget",
       "type": "VideoWidget",
       "x": 1,
       "y": 1,
       "width": 2,
       "height": 2,
       "datasource": {
          "source": "SavedSearch",
          "config": {
             "type": "QUERY",
             "id": "1234"
          }
       },
       "widgetSettings": {
          "restrictSearch": true
       }
    }

## Static Content Widget

For the Static Content widget, set `type` to StaticContentWidget.

You cannot use a saved search for this widget type, because its content is independent from any search.

The following table describes the options that you can use in the `widgetSettings` object.

Property | Required | Type | Description | Default
--- | --- | --- | --- | ---
`html` | Yes | String | The HTML to display in the widget. |

Example widget configuration:

    {
       "name": "Static Content",
       "type": "StaticContentWidget",
       "x": 1,
       "y": 1,
       "width": 2,
       "height": 2,
       "widgetSettings": {
          "html": "<h1>Hello World!</h1>"
       }
    }

## Static Image Widget

For the Static Image widget, set `type` to StaticImageWidget.

You cannot use a saved search for this widget type, because its content is independent from any search.

The following table describes the options that you can use in the `widgetSettings` object.

Property | Required | Type | Description | Default
--- | --- | --- | --- | ---
`url` | Yes | String | The URL of the image to display in the widget. |

Example widget configuration:

    {
       "name": "Static Image",
       "type": "StaticImageWidget",
       "x": 1,
       "y": 1,
       "width": 2,
       "height": 2,
       "widgetSettings": {
          "url": "http://example.com/image.png"
       }
    }

## Current Time/Date Widget

For the Current Time/Date widget, set `type` to CurrentTimeWidget.

You cannot use a saved search for this widget type, because its content is independent from any search.

The following table describes the options that you can use in the `widgetSettings` object.

NOTE: The current time/date widget uses the `moment.js` library to format dates. For more information about the available formats, refer to the `moment.js` documentation.

Property | Required | Type | Description | Default
--- | --- | --- | --- | ---
`dateFormat` | No | String | The date format to display. This option takes a `moment.js` date format string. | ll
`timeFormat` | No | String | The time format to display. This option takes a `moment.js` time format string. | HH:mm z
`timeZone` | No | String | The timezone to use in the date/time display. This option takes a `moment.js` timezone string. By default, the `moment.js` library attempts to display the local timezone. |

Example widget configuration:

    {
       "name": "Current Time Date",
       "type": "CurrentTimeWidget",
       "x": 1,
       "y": 1,
       "width": 2,
       "height": 2,
       "widgetSettings": {
          "timeFormat": "HH:mm:ss Z"
       }
    }

## Time Last Refreshed Widget

For the Time Last Refreshed widget, set `type` to TimeLastRefreshedWidget.

You cannot use a saved search for this widget type, because its content is independent from any search.

The following table describes the options that you can use in the `widgetSettings` object.

NOTE: The time last refreshed widget uses the `moment.js` library to format times. For more information about the available formats, refer to the `moment.js` documentation.

Property | Required | Type | Description | Default
--- | --- | --- | --- | ---
`dateFormat` | No | String | The date format to display. This option takes a `moment.js` date format string. | HH:mm z
`timeZone` | No | String | The timezone to use in the date/time display. This option takes a `moment.js` timezone string. By default, the `moment.js` library attempts to display the local timezone. |

Example widget configuration:

    {
       "name": "Time Last Refereshed",
       "type": "TimeLastRefreshedWidget",
       "x": 1,
       "y": 1,
       "width": 1,
       "height": 1
    }

_FT_HTML5_bannerTitle.htm