Widget Docs

What is a .wgt file?

A .wgt file is a ZIP archive with a renamed extension. Unzip it and you get a standard web project. The only mandatory addition is a config.xml in the root.

my-widget/
├── index.html      # entry point (default, configurable in config.xml)
├── config.xml      # W3C Widget manifest — required
├── icon.png        # optional but recommended
└── ...             # any other assets, JS, CSS, fonts

The player unzips the .wgt, reads config.xml, and opens the start file in its embedded browser. From that point on it’s a normal web page.

config.xml

The manifest declares metadata, the entry point, and the parameters the widget accepts. It follows the W3C Packaged Web Apps spec.

Minimal example:

<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns="http://www.w3.org/ns/widgets"
        id="com.example.my-widget"
        version="1.0.0">

    <name>My Widget</name>
    <description>Does something useful.</description>
    <author>Your Name</author>
    <content src="index.html"/>
    <icon src="icon.png"/>

</widget>

Parameters

Parameters are defined via <preference> elements and passed to the widget as URL query parameters by the player.

W3C: <preference>

The W3C spec defines three attributes:

name — the parameter name
value — the default value
readonly — prevents the widget from overwriting the value via the Widget API

<preference name="feedUrl" value="https://example.com/rss" readonly="false"/>

IAdea Extensions

IAdea extended <preference> with a proprietary ia: namespace to add typed inputs, defaults, tooltips, and validation. Spec-conform since the W3C explicitly allows proprietary extensions in separate namespaces. As it was never officially documented the following is based on reverse engineering:

ia:types — input type: text, integer, color
ia:default — default value (replaces W3C value)
ia:mandatory — marks the parameter as required
ia:tooltip — label or hint shown in the CMS form
ia:previewbg — uses the color value as a background in the CMS preview

<preference name="url" ia:types="text" ia:mandatory="true" ia:tooltip="URl of RSS Feed" />
<preference name="font_size" ia:default="30" ia:tooltip="Font size"  ia:types="integer"  />
<preference name="bgcolor" ia:types="color"  ia:tooltip="Background color"  ia:default="#008080" ia:previewbg="true"/>
<preference name="color" ia:types="color"  ia:tooltip="Text color"  ia:default="#ffffff" />

Inside index.html, read them like any URL parameter:

const params = new URLSearchParams(window.location.search);
const feedUrl = params.get('feedUrl');

Compatible CMS software reads the config.xml and generates an input form automatically. The person maintain the playlist fills in values.

Building a .wgt file

A widget is packaged by zipping the contents of the project directory and renaming the archive to .wgt. The config.xml must be in the root of the archive, not inside a subdirectory.

# Linux / macOS
cd my-widget/src
zip -r ../dist/my-widget.wgt .

# or use the Makefile provided by the IDE plugins
make

Local testing

Open index.html directly in a browser and pass parameters as URL query strings: