Write a widget

This page is for developers who want to add a feature to the frame, or understand how the existing ones (Clock, Weather, Calendar, Photos, Home Assistant and Cards) are built. When you finish it you will have a working widget, and you will know every hook the server, the frame page and the admin offer, and the rules that keep widgets independent of each other and of the core.

A widget is one folder, web/app/widgets/<id>/. Put the folder there and the widget exists on the server, in the cron fetcher, on the frame and in the admin. Delete it and it is gone from all four. No core file names a widget, and a test makes sure none ever does.

How a widget is wired in

flowchart TD
    dir["web/app/widgets/&lt;id&gt;/"] --> wp["widget.php<br/>the definition"]
    dir --> icon["icon.svg"]
    dir --> frame["frame/<br/>home.php, pages.php, overlay.php,<br/>widget.js, *.css"]
    dir --> adminf["admin/<br/>widget.js, *.css"]
    dir --> routes["routes.php, admin_routes.php"]
    dir --> fetch["fetch.php, fetch_lib.php"]
    dir --> tests["tests/*_test.php"]
    wp --> reg["Registry: widgets.php<br/>glob widgets/*/widget.php"]
    reg --> dash["Dashboard JSON<br/>data, page, pageIf"]
    reg --> self["Kiosk self GET<br/>self, origins, secrets"]
    reg --> adminlist["Admin widget list and save<br/>settings, types, info, on_save"]
    reg --> csp["Page CSP<br/>csp"]
    reg --> cron["Cron needs<br/>needs"]
    fetch --> cronloop["Cron loop<br/>fetch/fetch.php"]
    frame --> view["views/dashboard.php<br/>home cells, pages, overlay,<br/>script tags, icon sprite, CSS bundle"]
    adminf --> adminshell["views/admin.php<br/>script tags, CSS bundle"]
    routes --> fc["Frame front controller"]
    routes --> ac["Admin front controller"]

The registry (widget_names()) is glob(app/widgets/*/widget.php), sorted, with the id checked against ^[a-z][a-z0-9_]{0,31}$. Everything else is looked up by that id. File paths are built only by widget_path($id, $file), which throws for an unknown id, so no request can reach a path outside a registered widget.

Build your first widget

You will make a widget called Greeter that shows a line of text sent by the server. It needs five files and no core change.

Before you start, set up a development copy and sign in to the admin with a frame claimed (see the API reference for enrolling a frame without a device).

1. Create the folder web/app/widgets/greeter/ and, inside it, widget.php:

   php

   <?php
   
   declare(strict_types=1);
   
   return [
       'label' => 'Greeter',
       'description' => 'Shows a line of text.',
       'home' => ['row' => 2, 'order' => 99, 'span' => 1],
       'settings' => [],
       'needs' => fn(array $cfg): array => [],
       'data' => fn(array $cfg, Cache $c, Frame $f): array => ['text' => 'Hello from Greeter'],
   ];
   

2. Add icon.svg. It holds only the inside of a 24 by 24 stroke icon, with no <svg> wrapper:

   xml

   <circle cx="12" cy="12" r="9"/><path d="M8 12h8"/>
   

3. Create frame/home.php, the markup that goes inside the widget's home cell:

   php

   <span id="greeter-text" class="greeter-text"></span>
   

4. Create frame/widget.js. The shape is fixed: strict mode, one function that calls itself, one F.widget({...}).

   js

   "use strict";
   (() => {
     const F = window.Frame;
   
     F.widget({
       id: "greeter",
       update(data) {
         if (data === null) return false;
         F.$("greeter-text").textContent = data.text;
       },
     });
   })();
   

5. Create frame/widget.css. Every selector starts with .w-greeter:

   css

   .w-greeter .greeter-text { font-size: 28px; color: var(--soft); }
   

6. Run php tests/run.php and vendor/bin/phpstan analyse from web/. The registry, scope, security and isolation tests pick up the new folder by themselves.

7. In the admin, open the frame and its Widgets panel and switch on Greeter. Saving bumps the frame's config_version, so the dashboard reloads on its next poll (within 20 seconds). A Greeter card appears in the second row of the home grid with your text.

You just added a widget without editing a core file. Switch it off in the admin, and the card goes. Delete the folder, and the frame, the admin and the cron job forget it; its leftover frame_widgets rows are ignored.

Directory layout

Fragments (home.php, pages.php, overlay.php) are plain PHP files that print HTML. They may not contain style=, an on…= handler or <script>. Element ids must be unique across the whole page, so prefix yours with the widget id.

A widget that needs its own table must add a core migration. Per-widget migrations do not exist yet.

The definition: widget.php

widget.php returns an array. Only a few keys are required; the rest are optional hooks. A hook that is absent is not called.

Hooks run with these guarantees:

• needs, data, self, origins, secrets and pageIf run only for enabled widgets of active frames whose id is still in the registry.
• $cfg is the widget's saved settings for that frame, decoded from JSON.
• self and secrets are wrapped so that an exception is logged and the widget contributes nothing; the page and the other widgets are unaffected.
• data returning [] is sent as {}. A widget that is off is absent from the dashboard JSON, which is how the frame page tells "off" from "on but empty".

Settings and setting types

settings maps each key to a type. A type says how a value is validated and what its default is. Three core types are always available:

A widget adds its own types under types:

'types' => [
    'my_text' => [
        'default' => '',
        'secret'  => false,                       // optional
        'check'   => fn(mixed $v, string $key, PDO $db): string =>
            is_string($v) && mb_strlen($v) <= 40 ? $v : throw new FieldError('config', "$key must be at most 40 characters"),
    ],
],

check returns the clean value or throws FieldError('config', $message), which the admin API turns into a 422. Type names are global: two widgets declaring the same name throws a LogicException. A new type also needs a control in the widget's admin module, or the admin shows no field for it.

How a save is processed (PUT /api/frames/{id}/widgets/{widget}):

1. on_save($incoming, $stored) runs first, if the widget has it.
2. Secrets that the request left out are copied back from the stored config.
3. Every declared setting is validated: a missing key takes its type's default and is checked like any other value, so a type whose default fails its own check makes that setting required. An undeclared key is a 422.
4. The result is stored and the frame's config_version goes up by one, but only if something changed.

Secret settings ('secret' => true) are never returned by the admin API. Omit the key in a PUT to keep the stored value; send "" to clear it. Use the info hook to tell the admin whether one is set (for example token_set). The Home Assistant token and the Nextcloud album link work this way.

Seeding on claim: default

When an admin claims a frame, every widget with a default hook gets a frame_widgets row (ON CONFLICT DO NOTHING, so it never overwrites). enabled and config are functions of the database, so a default can depend on existing Library records. Clock, Weather and Calendar use it. Widgets without it start absent, which is off.

Home cell

home places the widget's card on the home screen and needs frame/home.php. The grid has four columns and two rows.

Pages: page and pageIf

'page' => ['Week', 'calendar'] adds a rail item labelled "Week" with the icon calendar. The item opens the page whose data-page equals the widget id, so frame/pages.php needs a <section data-page="<widget id>">. A widget can instead register a launch hook, which gives a rail item with no page of its own (Home Assistant does this). pageIf hides the rail item when it returns false; the dashboard JSON lists the visible items in pages as {widget, label, icon}. A widget may have more pages than the one on the rail (the calendar has a second one that its home card opens). Page ids must be unique across widgets and may not be home.

Facts for the admin: info

Whatever info returns is added to the widget's row in GET /api/frames/{id}/widgets as info. Use it for state the admin should show but the config does not hold: the effective URL, whether a secret is set, a count, an error.

Values for the kiosk: self, origins, secrets

These feed the kiosk's GET /api/v1/frames/{id} (the "self GET").

• self returns keys merged into the body. A null value omits the key. The core default for photos is [], meaning "clear your cache", so a deleted or disabled photos widget degrades the same way. Changing the shape of the self GET is a change to a frozen contract: add keys, never rename or remove them. Shipped kiosks ignore keys they do not know.
• origins returns the origins the kiosk may navigate to besides the frames site. The kiosk takes the first entry as the Home Assistant origin, so only one widget may declare this hook. A test fails if a second does.
• secrets returns values placed under widget_secrets.<id> in the self GET, and only when the request carried the Authorization header. They never appear in the dashboard JSON or in any admin response. The kiosk reads only the Home Assistant token today; a new key needs a kiosk change before it does anything.

Page security policy: csp

csp adds sources to the dashboard and admin Content Security Policy, for example ['img-src' => ['https://photos.example.org']]. A test limits this to img-src, media-src and connect-src, and each source must be a plain https origin. A widget can never loosen script-src or style-src.

Host checks: checks

bin/migrate.php calls each widget's checks and prints the strings as WARNING (<id>): …. A string that starts with NOTE: prints as information. Use it for a missing system tool or an unsupported setting. It does not fail the migration.

Options from config.php

An operator can pass options to a widget under widgets.<id> in config.php. They arrive untouched in the constant WIDGET_CONFIG['<id>']. Validate them yourself when you read them, and throw ConfigError for a bad value, as photos_limits() does.

The frame page

The core page (frame.js) owns the rail, the Dim button, the Back button, the idle timer, the offline badge, the 20-second poll, reloading when the code changes, and the home grid. A widget supplies markup and a small script.

What the server composes

views/dashboard.php walks the registry and writes, for each widget that has the files:

Every script is defer, so all of them have run before the core starts on DOMContentLoaded.

Registering: Frame.widget

F.widget({
  id: "photos",
  pages: { photos: { fullscreen: true, sticky: true } },
  init(ctx) {},
  update(data, ctx) {},
  tick(now) {},
  onShow(pageId) {},
  onHide(pageId) {},
  homeTarget() {},
  idlePage() {},
  busy() {},
  railItems() {},
  launch(pageId) {},
  layout(span) {},
});

Every hook is optional, and every call is wrapped in try/catch. A widget that throws is marked failed: its cell goes empty and the other widgets keep running. Check the browser console on the device or in a desktop browser for widget <id> failed in <hook>.

pages is an object keyed by page id with options:

Helpers on window.Frame

Rules that tests enforce on frame/widget.js:

• The file is "use strict";, then one (() => { … })();, then ends.
• It contains exactly one .widget( call (do not write that text in a comment), and it registers id: "<the folder name>".
• It does not use document.write, eval( or innerHTML.
• Core frame.js never names a widget.

Write text with textContent and build elements with createElement. Everything the server sends is data, not markup.

CSS

All frame/*.css files are concatenated into one frame.css: the core file first, then each widget's files, widgets and files sorted by name. The version is a hash over every part's path, modification time and size, so a change reaches the frame on its next reload.

Because a rule in one widget must not change another, a test checks that:

• Every selector starts with .w-<id> (not followed by a word character or hyphen) or body.w-<id>-<name>.
• @keyframes are named w-<id>-<name>. No other at-rule is allowed.
• No rule uses !important.

You may use the core variables --bg, --surface, --line, --fg, --dim, --past, --accent, --accent-bg, --warn, --warn-bg, --soft, --font, and the core classes .card, .sect-label, .page-title, .page-empty, .hscroll and .xfade. body.page-fullscreen and .offline are hooks you can style against.

The admin

Most widgets need no admin code. The admin builds a settings panel for each widget from its settings, using its own controls for the three core types. You need admin/widget.js only when a widget has a custom control, an extra panel, or its own top-level view.

(function () {
"use strict";
const { h, rowField } = Admin;

Admin.widget({
  id: "photos",
  controls: { my_text: (w, key, ctx) => control },   // one per widget-local setting type
  load: (frame) => Promise,                            // extra data per frame; arrives as ctx.extra[id]
  panel: (frame, w, ctx) => Panel,                     // replaces the generic settings panel
  views: [{ path: "/photos", nav: "Photos", render: async () => ({ title, nodes }) }],
});
})();

A control that is missing for a widget-local type renders nothing, so the admin cannot set that setting. Add one.

window.Admin is the frozen toolbox the panels use: h (element builder), fill, append, btn, pill, svgIcon, icons, uid, api, act, toast, modal, confirmDialog, formField, groupField, rowField, chipField, panelHead, Panel, showSwitch, makeForm, formDialog, ago, when, fmtTz, clockTime, dayLabel, widgetsHref, addLocationDialog, addCalendarDialog, route, upload and control. Read the existing modules for examples: ha/admin/widget.js for custom controls, photos/admin/widget.js and notes/admin/widget.js for panels and views.

The same rules apply as on the frame: build DOM with h(), never innerHTML, no inline styles. Admin CSS goes in admin/*.css, is bundled into admin.css the same way, and should be scoped to your widget.

Routes

A widget can add HTTP routes. routes.php and admin_routes.php each return a function that builds a list of routes. A route is [METHOD, regex, handler], and a handler takes the regex matches and never returns: it ends with json_out(), empty_out(), an asset response or an exception.

<?php

declare(strict_types=1);

return function (PDO $db, string $base): array {
    return [
        ['GET', '#^/api/greeters$#', fn() => json_out(200, ['items' => []])],
        ['POST', '#^/api/greeters$#', fn() => greeter_create($db, $base)],
    ];
};

Rules:

• Core routes match first. A test checks that no widget route regex matches any core path, for any method.
• Admin routes are protected before your code runs. admin_api() has already required a signed-in session and a same-origin request, and requires the CSRF token for anything that is not a GET. You must still call admin_require_reauth() yourself for destructive actions, and use admin_json_body(), admin_invalid() and admin_unique() for input and errors.
• Frame routes authenticate themselves. Call frame_auth($db), then frame_require_self($row, $id) and frame_require_active($row). Public pages that use a secret link do their own token check and rate limits; copy photos/handlers.php or notes/handlers.php.
• Read input with request_json($allowed, $maxBytes), request_body() or request_image(). They give you 415, 413 and 422 for free.
• Return errors by throwing HttpError. See the API conventions.
• New routes need a security review, and a review of the REST shape. See the security page.

The Apache .htaccess files cap request bodies at 64 KiB (frames) and 16 KiB (admin). An endpoint that takes a large upload needs a narrow LimitRequestBody exception keyed on THE_REQUEST, the way the photo and kiosk-release endpoints have. Keep it as narrow as they are.

Cron fetchers

A widget that needs data from the internet declares cache keys in needs and supplies a fetch.php. Only the cron loop (app/fetch/fetch.php) loads fetch.php, and only fetch code makes outbound requests. A test fails if any widget file calls cURL or opens a socket directly, or if a widget file other than fetch.php requires something from app/fetch/. Go out through http_get() (below).

<?php

declare(strict_types=1);

require_once __DIR__ . '/fetch_lib.php';

return [
    'prefix'     => 'gr',
    'expand'     => fn(string $need): array => preg_match('/^gr:(\d+)$/', $need, $m) === 1 ? ["gr:{$m[1]}:now"] : [],
    'ttl'        => fn(string $key): int => 600,
    'fetch'      => fn(string $key, PDO $cache, PDO $frames): mixed => gr_fetch($key),
    'due'        => null,        // optional
    'everyTick'  => false,
    'crashGuard' => false,
    'backoff'    => 60,
];

Each 15-second tick runs every everyTick key that is due and at most one other stale key, the one fetched longest ago. Read stored values in data with $c->get($key), which returns ['v' => decoded, 'at' => time] or null.

To go out, use http_get($url, $hosts, [], $accept, $maxBytes) or http_get_json() from app/fetch/http.php. They enforce HTTPS, a host allow-list, no redirects, a size cap and timeouts. Take the host list from config.php (CALENDAR_HOSTS, PHOTO_HOSTS) or declare a fixed one for a public API.

Photo sources

The photos widget shows pictures from one source per frame. A source is a folder, widgets/photos/sources/<id>/, found the same way widgets are. The widget merges every source's settings, types and csp, so no other file names a source. Delete a source folder and the frames that used it show no photos. Today the sources are nextcloud (a public album link) and local (an album in the photo library).

sources/<id>/source.php returns:

Photo ids are integers. A source that needs the cron fetcher also adds sources/<id>/fetch.php returning ['fetch' => fn(string $key, array $cfg, PDO $cache, ?callable $http): list<array{id: int, mtime: ?int}>]. Its keys must look like ph:<16 lowercase hex>, because the photos widget's cron prefix is ph and it accepts only that shape. The widget picks 50 photos a day per frame from the catalog, favoring recently added ones.

A source that serves photos itself (serve) must keep every query to status = 'approved'. See the security page.

Isolation rules

The point of the design is that you can remove or add a widget without touching anything else. These tests keep it true. They run with php tests/run.php:

When you delete a widget, expect: the frame page reloads (the code version includes the widgets folder's modification time), its rail item and pages vanish, its home cell is empty (row 1) or closes up (row 2), its admin row and panel disappear, cron stops fetching its keys, and the kiosk's self GET falls back to the core defaults. Its frame_widgets rows, tables and cache rows stay and are ignored; delete them by hand if you want them gone.

The checklist for a new widget:

1. Create widgets/<id>/ with widget.php and icon.svg.
2. Add frame/widget.js, frame/widget.css and frame/home.php and/or frame/pages.php as needed.
3. Add lib.php, fetch.php, routes.php, admin_routes.php or admin/widget.js only if you need them.
4. Put the tests in widgets/<id>/tests/.
5. Run the tests and PHPStan. Turn the widget on per frame in the Widgets panel.
6. The only core file you may touch is config.php for deployment values.

Related

• Developer start: set up, tests and the build
• API reference: the dashboard JSON, the self GET and the widget endpoints
• Database: the frame_widgets table
• Security: the rules that apply to routes, uploads and secrets