> 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/developer/widgets/creating-a-module/data-provider.md).

# Data Provider

If you are making a new module that has data then this data will need to be requested/parsed and made available to the widget. There are two ways to do this:

* Setting a Widget Provider in the `class` attribute. This is a good choice if your data source does not require any special authentication flows or complex configuration.
* Handling the `WidgetDataRequestEvent` using a connector or custom middleware. This is necessary when you have more complex requirements, such as authentication flows; or when you can supply more than one data type.

Xibo provides an instance of `DataProviderInterface` to both.

## The DataProvider Interface

Whether you’re using a WidgetProvider or handling the `WidgetDataRequestEvent` event, you will interact with the `DataProviderInterface` to add data items, metadata and images to your data points.

The most basic usage of the data provider will be to call `addItem()` for each data point needed. These should be a `JsonSerializable` object or key/value array per item.

Retrieving and parsing data will likely depend on module settings and properties, which can be retrieved with `getSetting()` and `getProperty()`. A Guzzle HTTP client has been provided with `getGuzzleClient()`, preconfigured with any proxy settings.

If the request has been handled, you must call `setIsHandled()` on the data provider.

## Use the data provider

### Using a Widget Provider

To use a widget provider a new class should be created and added to the `class` attribute in the module XML. This class should implement `WidgetProviderInterface` and add logic to the `fetchData` method.

### Using a Connector

Create a new [connector](/developer/widgets/connectors.md) and register it with the dispatcher to handle the `WidgetDataRequestEvent`:

{% code title="Connector::registerWithDispatcher" %}

```php
public function registerWithDispatcher(EventDispatcherInterface $dispatcher): ConnectorInterface
{
    $dispatcher->addListener(WidgetDataRequestEvent::$NAME, [$this, 'onDataRequest']);
    return $this;
}
```

{% endcode %}

Inside the method which will handle the event (`onDataRequest` in the above example) the source of the event should be tested to ensure the event is for the correct datatype/module using:

```php
$event->getDataProvider()->getDataSource()
```

{% hint style="info" %}
It is also possible to handle the `WidgetDataRequestEvent` in a custom middleware, which can be useful if the user does not need to make configuration changes or otherwise see a connector in the user interface.
{% endhint %}


---

# 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/developer/widgets/creating-a-module/data-provider.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.