> 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 dynamically by asking a question.

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

```
GET https://docs.xibosignage.com/developer/widgets/creating-a-module/data-provider.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.