commit fa442b1fef8decd7a991ed54a1f8b2f809ea4a44 Author: droideparanoico Date: Tue Jun 16 09:55:30 2026 +0000 Initial release: arr-calendar widget with partial-services support - Self-contained YML: all CSS inlined (no global.css edit needed) - Vanilla JS client with MutationObserver bootstrap - Slide+fade month navigation via rAF (works in this Dynacat build) - Popover portaled to to escape backdrop-filter containing blocks - Per-service enabled flag, unconfigured services silently skipped - Status

.${BASE_HOST}`. | required | + +Get an API key from each *arr under **Settings → General → API Key**. + +If you set the env var on the Dynacat container itself, no per-service +configuration is needed — defaults to +`https://sonarr.${BASE_HOST}`, `https://radarr.${BASE_HOST}`, +`https://lidarr.${BASE_HOST}`. To use a different URL for a service, set +the corresponding `*-url` option in your `$include` of `arr-calendar.yml` +(see [Customising URLs](#customising-urls) below). + +### 2. File layout + +``` +/appdata/dynacat/ + config/ + dynacat.yml # main config (edit to add the script tag) + arr-calendar.yml # <-- this repo, copy here + assets/ + arr-calendar.js # <-- this repo, copy here + global.css # (untouched; widget CSS is inlined in the YML) +``` + +### 3. Edit `dynacat.yml` + +Add the script tag under `document.head`: + +```yaml +server: + assets-path: /app/assets + +document: + head: | + +``` + +Then `$include` the widget in a page column (any column size — it adapts): + +```yaml +pages: + - name: Home + columns: + - size: small + widgets: + - $include: arr-calendar.yml +``` + +### 4. Restart the container + +**YML edits do not recompile the Go template on the fly.** Glance/Dynacat +parses each `custom-api` template once on first render and caches the +compiled `*template.Template` in memory. File mtime updates, `touch` and +edits to the file do not invalidate the cache. After every edit to +`arr-calendar.yml`, restart the container: + +```bash +docker restart dynacat +``` + +(or via your container manager — Dockhand, Unraid UI, etc.). The error +message you'll get if you forget is the dreaded +`Config has errors: custom-api widget: parsing template: ...` — see +[Troubleshooting](#troubleshooting) below. + +### 5. Hard-refresh the browser + +`Ctrl+Shift+R` (or `Cmd+Shift+R` on macOS) to bypass the browser cache. + +## Customising + +All options live in the top of `arr-calendar.yml` under `options:`: + +```yaml +- type: custom-api + options: + sonarr-url: https://sonarr.example.com + sonarr-key: ${SONARR_KEY} + radarr-url: https://radarr.example.com + radarr-key: ${RADARR_KEY} + lidarr-url: https://lidarr.example.com + lidarr-key: ${LIDARR_KEY} + exclude-physical: true + past-days: 90 + future-days: 90 +``` + +| Option | Default | Notes | +| ---------------- | ------------------- | ----- | +| `sonarr-url` | `https://sonarr.${BASE_HOST}` | Override if your Sonarr is on a different host | +| `sonarr-key` | `${SONARR_KEY}` | Set the env var instead of hard-coding | +| `radarr-url` | `https://radarr.${BASE_HOST}` | | +| `radarr-key` | `${RADARR_KEY}` | | +| `lidarr-url` | `https://lidarr.${BASE_HOST}` | | +| `lidarr-key` | `${LIDARR_KEY}` | | +| `exclude-physical` | `true` | When `true`, Radarr movies whose display date is a physical release are hidden. Set to `false` to show them. | +| `past-days` | `90` | How many days into the past to fetch (for the "this month" view, so the first week of the month shows releases from the previous month) | +| `future-days` | `90` | How many days into the future to fetch (should be ≥ 60 to cover the full ~2-month view) | + +If you want to keep the defaults but override the URLs, the cleanest +pattern is to copy the widget's options block into your main +`dynacat.yml` and `$include` the rest, or to edit `arr-calendar.yml` +directly. + +## Customising URLs + +The default URLs use the `BASE_HOST` env var and assume Sonarr/Radarr/Lidarr +are reachable as subdomains of that host. To use a different host for one +of the services, override the corresponding `*-url` option in your +`$include`. The YML supports Go template strings, so you can interpolate +env vars: + +```yaml +- type: custom-api + options: + sonarr-url: https://sonarr.${BASE_HOST} + sonarr-key: ${SONARR_KEY} + radarr-url: http://192.168.1.50:7878 # absolute override + radarr-key: ${RADARR_KEY} + lidarr-key: ${LIDARR_KEY} # omitted URL → defaults to https://lidarr.${BASE_HOST} +``` + +Note: at least one of the three `(url, key)` pairs must be set per service +for the service to be queried. An empty `*-key` skips the service +entirely — see [Partial-services support](#partial-services-support). + +## Partial-services support + +This is the headline feature. The widget keeps working with **any subset +of the three services configured**: + +- Set only `SONARR_KEY` → calendar shows only Sonarr releases (blue dots + only) +- Set all three → all three colours of dots appear +- Set none → soft empty-state message: *"Configure at least one of + SONARR_KEY, RADARR_KEY, or LIDARR_KEY in the container environment to + show releases."* + +A service is "configured" if both its URL and API key are non-empty. If +either is empty, that service's API is silently skipped — no request +goes out, no error widget appears, and the widget continues to render +with the remaining services. + +If a service is **configured** but **unreachable** (network down, +service dead, 401 from a wrong key), the same logic applies: that +service is skipped (the 5s HTTP timeout will trip), and the other +services continue to render. + +The status of each service is exposed to the client JS in a hidden +`

| withHeader ... │ +│ | getResponse │ +│ 4. Emit hidden

per release │ +└────────────────────────────────────────────────────────────┘ + │ + ▼ HTTP response, XHR-rendered +┌────────────────────────────────────────────────────────────┐ +│ Browser │ +│ */}} + + + + {{ $radarrUrl := .Options.StringOr "radarr-url" "" }} + {{ $sonarrUrl := .Options.StringOr "sonarr-url" "" }} + {{ $lidarrUrl := .Options.StringOr "lidarr-url" "" }} + {{ $radarrKey := .Options.StringOr "radarr-key" "" }} + {{ $sonarrKey := .Options.StringOr "sonarr-key" "" }} + {{ $lidarrKey := .Options.StringOr "lidarr-key" "" }} + {{ $excludePhysical := .Options.BoolOr "exclude-physical" false }} + {{ $pastDays := .Options.IntOr "past-days" 90 }} + {{ $futureDays := .Options.IntOr "future-days" 90 }} + + {{ $pastH := mul $pastDays 24 }} + {{ $futureH := mul $futureDays 24 }} + + {{ $start := offsetNow (printf "-%dh" $pastH) | formatTime "2006-01-02T15:04:05" }} + {{ $end := offsetNow (printf "+%dh" $futureH) | formatTime "2006-01-02T15:04:05" }} + {{ $nowIso := now | formatTime "2006-01-02T15:04:05" }} + + {{- /* A service is "configured" if BOTH the URL and the API key are set. + Unconfigured services are silently skipped — no request, no error. + + We declare $xxxData at the OUTER scope with an empty URL, which + Glance's getResponse() handles by returning a zero-valued response + with Response.StatusCode = 0 (see fetchCustomAPIResponse in + widget-custom-api.go: empty URL short-circuits to a no-op). The + outer-scope declaration is required because Go text/template + variables declared with `:=` inside an if-block are scoped to that + block — referencing them outside the block yields "undefined + variable". The if-block then reassigns the outer variable with `=` + when the service is enabled. */}} + {{ $radarrEnabled := and (ne $radarrUrl "") (ne $radarrKey "") }} + {{ $sonarrEnabled := and (ne $sonarrUrl "") (ne $sonarrKey "") }} + {{ $lidarrEnabled := and (ne $lidarrUrl "") (ne $lidarrKey "") }} + + {{- $radarrData := newRequest "" | getResponse }} + {{- $sonarrData := newRequest "" | getResponse }} + {{- $lidarrData := newRequest "" | getResponse }} + + {{- if $radarrEnabled }} + {{ $radarrReq := printf "%s/api/v3/calendar?start=%s&end=%s" $radarrUrl $start $end }} + {{- $radarrData = newRequest $radarrReq + | withHeader "Accept" "application/json" + | withHeader "X-Api-Key" $radarrKey + | getResponse }} + {{- end }} + + {{- if $sonarrEnabled }} + {{ $sonarrReq := printf "%s/api/v3/calendar?includeSeries=true&start=%s&end=%s" $sonarrUrl $start $end }} + {{- $sonarrData = newRequest $sonarrReq + | withHeader "Accept" "application/json" + | withHeader "X-Api-Key" $sonarrKey + | getResponse }} + {{- end }} + + {{- if $lidarrEnabled }} + {{ $lidarrReq := printf "%s/api/v1/calendar?start=%s&end=%s" $lidarrUrl $start $end }} + {{- $lidarrData = newRequest $lidarrReq + | withHeader "Accept" "application/json" + | withHeader "X-Api-Key" $lidarrKey + | getResponse }} + {{- end }} + + {{ $anyConfigured := or $radarrEnabled $sonarrEnabled $lidarrEnabled }} + +

+ +

+ + +

+ + {{- /* Soft empty-state message when the user hasn't configured any service. + We intentionally do NOT render the giant widget-error banner — partial + availability (e.g. Sonarr-only) is success, not an error. */}} + {{ if not $anyConfigured }} +

+ Configure at least one of SONARR_KEY, RADARR_KEY, + or LIDARR_KEY in the container environment to show releases. +

+ {{ end }}