From d7a468c80620fbaa2818b3d9ebe16cf3f1e294d6 Mon Sep 17 00:00:00 2001 From: codebude Date: Fri, 12 Jun 2026 08:27:24 +0200 Subject: [PATCH] Add customapi widget Dashy integration to docs --- docs/api/integrations/dashy.md | 77 ++++++++++++++---- .../integrations-dashy-customapi.png | Bin 0 -> 9325 bytes ...dashy.png => integrations-dashy-embed.png} | Bin 3 files changed, 59 insertions(+), 18 deletions(-) create mode 100644 docs/public/screenshots/integrations-dashy-customapi.png rename docs/public/screenshots/{integrations-dashy.png => integrations-dashy-embed.png} (100%) diff --git a/docs/api/integrations/dashy.md b/docs/api/integrations/dashy.md index 73ee033..ad63d69 100644 --- a/docs/api/integrations/dashy.md +++ b/docs/api/integrations/dashy.md @@ -1,25 +1,57 @@ # Dashy LibrisLog can be integrated into [Dashy](https://dashy.to/), a self-hosted -dashboard for your services, using its -[HTML embedded widget](https://dashy.to/docs/widgets#html-embedded-widget). +dashboard for your services, using one of its widget types: -This widget displays your reading statistics as styled stat cards directly on -your Dashy dashboard. +- **[Custom API widget](#custom-api-widget-recommended)** (Dashy ≥4.3.1) — + a simple, built-in widget that fetches your stats directly (recommended). +- **[HTML embedded widget](#html-embedded-widget)** — a fully customizable + widget with styled stat cards. ## Prerequisites - A running LibrisLog instance reachable from your Dashy server - An [API key](/api/integrations/#api-keys) with access to the statistics endpoint -- **CORS must be configured** — add your Dashy URL to the - [`CORS_ORIGINS`](/guide/configuration#core-settings) environment variable - of the LibrisLog backend so that the browser can fetch the API directly -## Configuration +## Custom API Widget (Recommended) + +Since Dashy v4.3.1 you can use the built-in +[custom API widget](https://dashy.to/docs/widgets#api-response). +Add the following to your Dashy `conf.yml`: + +```yaml +widgets: + - type: customapi + options: + url: /api/books/stats + headers: + X-API-Key: "" + refreshInterval: 60000 + display: block + mappings: + - field: books_read + label: Read + format: number + - field: books_reading + label: Reading + format: number + - field: books_want_to_read + label: Want to read + format: number + - field: total_books + label: Total + format: number +``` + +The `refreshInterval` is specified in milliseconds. `60000` equals 1 minute. + +## HTML Embedded Widget -Add the following to the Dashy `conf.yml` under the section or item where you -want the widget to appear: +For full control over the appearance you can use the +[HTML embedded widget](https://dashy.to/docs/widgets#html-embedded-widget). + +Add the following to your Dashy `conf.yml`: ```yaml widgets: @@ -112,6 +144,10 @@ widgets: })(); ``` +The `updateInterval` is specified in seconds. `300` equals 5 minutes. + +## Placeholders + Replace the placeholders with your own values: | Placeholder | Example | Description | @@ -119,19 +155,24 @@ Replace the placeholders with your own values: | `` | `http://192.168.1.100:8000` | The base URL of your LibrisLog instance (http or https) | | `` | `lk_nRHsF3jxIBDa9u....` | An API key with access to the statistics endpoint | -The `updateInterval` is specified in seconds. `300` equals 5 minutes. - ## CORS -Since the widget runs inside the Dashy iframe and fetches the LibrisLog API -directly from the browser, you must add your Dashy URL to the +The embed widget runs inside the Dashy iframe and fetches the API directly from +the browser. You must add your Dashy URL to the [`CORS_ORIGINS`](/guide/configuration#core-settings) environment variable of -the LibrisLog backend. For example: +the LibrisLog backend: ``` -CORS_ORIGINS=["https://dashy.YOUR-DOMAIN"] +CORS_ORIGINS=[""] ``` -## Result +The custom API widget also requires CORS if Dashy is configured to render +widgets client-side. If CORS errors occur, add the origin as shown above. + +## Results + +### Custom API (API Response) Widget +![Dashy Custom API Widget](/screenshots/integrations-dashy-customapi.png) -![Dashy Widget](/screenshots/integrations-dashy.png) +### HTML Embed Widget +![Dashy HTML Embedded Widget](/screenshots/integrations-dashy-embed.png) diff --git a/docs/public/screenshots/integrations-dashy-customapi.png b/docs/public/screenshots/integrations-dashy-customapi.png new file mode 100644 index 0000000000000000000000000000000000000000..5c873630a93a84f7bfac4565c6f977869b7048e1 GIT binary patch literal 9325 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