> For the complete documentation index, see [llms.txt](https://docs.xibosignage.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xibosignage.com/layouts/layouts_editor_data_widgets.md).

# Data Widgets

Data Widgets rely on an external data source to show information on Layouts by using Elements.

## Overview

* Data source driven content.
* Separate Elements allow for flexibility.
* Provide fallback data to show.
* Control paging of data with Data Slots.
* Create Groups for easy duplication.
* Pull data from an alternative source on the same Layout.
* Utilise pre-made designs.

Each Data Widget has a set of **Elements** which are fed by a data source which allow a User flexibility in the placement of returned data rather than being bound by a rigid **Static Template** design:

* Click on a **Data Widget** to show all available **Elements**.

![Data Elements](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-c35571a9d1123239cfc531b57deb1547a633bcdd%2Fv4_layouts_data_elements.png?alt=media)

{% hint style="warning" %}
Data Elements are only available from the Layout Editor and are not available in the Playlist Editor. Users can however add Data Widgets using Static Templates.
{% endhint %}

### Configure

Each Element has a set of configurable options available from the **Properties Panel** once added:

![Element Properties](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-829b3271615edeffc877c9a2b500bd8997786e93%2Fv4_layouts_element_properties.png?alt=media)

{% hint style="warning" %}
An exclamation icon will be shown to prompt a User as to what needs to be actioned. The above example has yet to have a URL entered for an ICS feed! 
{% endhint %}

Options set from the **Configure** tab will apply to all Elements added to the Layout of the same Widget type.

{% hint style="success" %}
Create a **New Configuration** to select data from alternative data sources associated with the Widget! 
{% endhint %}

### Appearance

The **Appearance** tab includes options to configure how the data returned from the Element should look and includes transition effects and Data Slot configuration.

### Fallback Data

Create **Fallback Data** for selected Data Widgets and specify under what conditions it should be shown:

![Fallback Data](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-3b6a1f535ebaf87367c659ad281d2007bc582755%2Fv4_layouts_editor_data_widgets_fallback.png?alt=media)

* Click **Add New**.
* Complete the form fields with the required information.
* Save.

{% hint style="warning" %}
Fallback Data options will vary dependent on the Data Widget selected!
{% endhint %}

### Advanced

The Advanced tab is used to set Naming, provide specific durations, set the collection level of proof of play stats and enable items to be repeated to fill all Data Slots.

### Positioning

Use the **Positioning** tab (grid icon) to set precise positioning and Layering.

{% hint style="info" %}
 Elements have their own Canvas Layer, which can be used to determine where they appear in relation to other natively rendered Elements such as Playlists and Videos!
{% endhint %}

## Data Slots

When adding more than one of the same **Element**, handle the paging of returned data by specifying a **Data Slot** to use for each Element:

![Data Slots](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-4bdd6c66b57e3f5a462f77d9e294f4055f04b721%2Fv4_layouts_editor_data_slots.png?alt=media)

For example, the image above shows 2 **Description Elements** from the **Calendar Widget** have been added. One has a **Data Slot of 1** the other a **Data Slot of 2.** If 10 (Calendar Events) items were returned, Data Slot 1 would show items 1,3,5,7,9 with Data Slot 2 showing items 2,4,6,8,10.

Data Slots are set from the **Appearance** tab of the **Properties Panel** for the selected Element.

In addition Elements have the option to **Pin this slot** so that the first data item to appear in that slot will remain for the entire duration of the Widget and won't cycle through data items.

{% hint style="info" %}
Users can set whether to **Repeat items** in order to fill all data slots to ensure there are no empty slots by using the checkbox on the **Advanced** tab of the Properties Panel! 
{% endhint %}

## Grouping Elements

Group Elements of the same Data Widget together to make it easier to build designs:

* Add Elements to the Layout, position and style using the **Appearance** tab.
* Hold down the shift key and click into each Element you wish to group.
* Once selected, release the shift key and right click.
* Select **Group elements**.

![Grouping Elements](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-aa83b97c070c3b6f4da756d3174ff666aae9d7c1%2Fv4_layouts_grouping_elements.png?alt=media)

{% hint style="success" %}
Groups can also include **Global Elements**
{% endhint %}

{% hint style="warning" %}
All Data Elements need to share the same **Data Slot** and **Effect** when grouping
{% endhint %}

Groups can be easily duplicated:

* Right click and select **Duplicate**.

![Duplicated Elements](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-25b34c1647ec3fa8da64c4db3d7dc0cdf456d6a5%2Fv4_layouts_duplicated_elements.png?alt=media)

Edit **Data Slots** for each group to control data paging:

![Data Slots Groups](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-8d7e47d02a333784e4fe111e04e4d943afdfa75d%2Fv4_layouts_data_slots_groups.png?alt=media)

Make edits to the **Appearance** of each Element in a group:

* Click the pencil icon in the top right corner.
* Click in each Element and use the Appearance tab to make changes.
* Click out of the group or click the X to exit editing.

Edits can be made to the **Configuration** but it will apply to all Elements added.

Ungroup elements from the right click menu!

## New Configurations

New Configurations can be created in order to have alternative configuration options/different data source associated with the Widget:

* Right click an Element or Element Group and select **New Configuration** from the menu.
* Select an alternative data source / alternative configuration from the **Configure** tab.

## Stencils

Selected Data Widgets include pre made designs of Element Groups called **Stencils** to assist Users with creating content simply and quickly:

* Stencils are added in exactly the same way, positioned and resized.
* Complete the fields to **Configure**.
* Edit the **Appearance** by clicking on the pencil icon in the top right of the group.
* Select an Element in the group to make edits.

{% hint style="success" %}
Right click to ungroup to customise further!
{% endhint %}

## Static Templates

Static Templates are included for specific Widgets. Templates can be configured to affect the behaviour of returned results as well as alter styling options.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.xibosignage.com/layouts/layouts_editor_data_widgets.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.