From b78ddeaf43875f6cdb0da9d51be059890d97d7d6 Mon Sep 17 00:00:00 2001 From: Julian Pawlowski <75446+jpawlowski@users.noreply.github.com> Date: Tue, 2 Dec 2025 16:47:36 +0000 Subject: [PATCH] feat(docs): update get_apexcharts_yaml service descriptions to clarify limitations and customization options --- custom_components/tibber_prices/services.yaml | 11 ++++++++++- custom_components/tibber_prices/translations/de.json | 2 +- custom_components/tibber_prices/translations/en.json | 2 +- custom_components/tibber_prices/translations/nb.json | 2 +- custom_components/tibber_prices/translations/nl.json | 2 +- custom_components/tibber_prices/translations/sv.json | 2 +- docs/user/automation-examples.md | 8 +++++++- docs/user/services.md | 10 +++++++++- 8 files changed, 31 insertions(+), 8 deletions(-) diff --git a/custom_components/tibber_prices/services.yaml b/custom_components/tibber_prices/services.yaml index cbe8673..d3d7f59 100644 --- a/custom_components/tibber_prices/services.yaml +++ b/custom_components/tibber_prices/services.yaml @@ -28,7 +28,16 @@ get_price: get_apexcharts_yaml: name: Get ApexCharts Card YAML description: >- - Returns a ready-to-copy YAML snippet for an ApexCharts card visualizing Tibber Prices for the selected day. Use this to easily add a pre-configured chart to your dashboard. The YAML will use the get_chartdata service for data. + ⚠️ IMPORTANT: This service generates a BASIC EXAMPLE configuration for ApexCharts Card as a starting point. It is NOT a complete solution for all ApexCharts features. + + + This integration is primarily a DATA PROVIDER. The generated YAML demonstrates how to use the `get_chartdata` service to fetch price data. Due to the segmented nature of our data (different time periods per series) and the use of Home Assistant's service API instead of entity attributes, many advanced ApexCharts features (like in_header, certain transformations) are not compatible or require manual customization. + + + You are welcome to customize the generated YAML for your specific needs, but please understand that comprehensive ApexCharts configuration support is beyond the scope of this integration. Community contributions with improved configurations are always appreciated - if you find a better setup that works, please share it so everyone can benefit! + + + For direct data access to build your own charts, use the `get_chartdata` service instead. fields: entry_id: name: Entry ID diff --git a/custom_components/tibber_prices/translations/de.json b/custom_components/tibber_prices/translations/de.json index b6f59e5..688ad07 100644 --- a/custom_components/tibber_prices/translations/de.json +++ b/custom_components/tibber_prices/translations/de.json @@ -791,7 +791,7 @@ }, "get_apexcharts_yaml": { "name": "ApexCharts-Karten-YAML abrufen", - "description": "Gibt einen fertigen YAML-Schnipsel für eine ApexCharts-Karte zurück, die Tibber-Preise für den ausgewählten Tag visualisiert. Verwende dies, um ganz einfach ein vorkonfiguriertes Diagramm zu deinem Dashboard hinzuzufügen. Das YAML verwendet den get_chartdata-Service für Daten.", + "description": "⚠️ WICHTIG: Dieser Service generiert eine GRUNDLEGENDE BEISPIEL-Konfiguration für die ApexCharts-Karte als Startpunkt. Es ist KEINE vollständige Lösung für alle ApexCharts-Funktionen. Diese Integration ist primär ein DATENLIEFERANT. Das generierte YAML zeigt, wie du den `get_chartdata`-Service zum Abrufen von Preisdaten nutzt. Aufgrund der segmentierten Natur unserer Daten (verschiedene Zeitabschnitte pro Serie) und der Nutzung von Home Assistants Service-API statt Entity-Attributen sind viele erweiterte ApexCharts-Funktionen (wie in_header, bestimmte Transformationen) nicht kompatibel oder erfordern manuelle Anpassung. Du darfst das generierte YAML gerne für deine spezifischen Bedürfnisse anpassen, aber bitte verstehe, dass umfassender ApexCharts-Konfigurations-Support außerhalb des Umfangs dieser Integration liegt. Community-Beiträge mit verbesserten Konfigurationen sind immer willkommen - wenn du ein besseres Setup findest, das funktioniert, teile es bitte, damit alle davon profitieren können! Für direkten Datenzugriff zum Erstellen eigener Diagramme nutze stattdessen den `get_chartdata`-Service.", "fields": { "entry_id": { "name": "Eintrags-ID", diff --git a/custom_components/tibber_prices/translations/en.json b/custom_components/tibber_prices/translations/en.json index ba6a597..60b8faf 100644 --- a/custom_components/tibber_prices/translations/en.json +++ b/custom_components/tibber_prices/translations/en.json @@ -787,7 +787,7 @@ }, "get_apexcharts_yaml": { "name": "Get ApexCharts Card YAML", - "description": "Returns a ready-to-copy YAML snippet for an ApexCharts card visualizing Tibber Prices for the selected day. Use this to easily add a pre-configured chart to your dashboard. The YAML will use the get_chartdata service for data.", + "description": "⚠️ IMPORTANT: This service generates a BASIC EXAMPLE configuration for ApexCharts Card as a starting point. It is NOT a complete solution for all ApexCharts features. This integration is primarily a DATA PROVIDER. The generated YAML demonstrates how to use the `get_chartdata` service to fetch price data. Due to the segmented nature of our data (different time periods per series) and the use of Home Assistant's service API instead of entity attributes, many advanced ApexCharts features (like in_header, certain transformations) are not compatible or require manual customization. You are welcome to customize the generated YAML for your specific needs, but please understand that comprehensive ApexCharts configuration support is beyond the scope of this integration. Community contributions with improved configurations are always appreciated - if you find a better setup that works, please share it so everyone can benefit! For direct data access to build your own charts, use the `get_chartdata` service instead.", "fields": { "entry_id": { "name": "Entry ID", diff --git a/custom_components/tibber_prices/translations/nb.json b/custom_components/tibber_prices/translations/nb.json index 0e0fd72..76b7f99 100644 --- a/custom_components/tibber_prices/translations/nb.json +++ b/custom_components/tibber_prices/translations/nb.json @@ -787,7 +787,7 @@ }, "get_apexcharts_yaml": { "name": "Hent ApexCharts-kort YAML", - "description": "Returnerer en klar-til-kopier YAML-snippet for et ApexCharts-kort som visualiserer Tibber-priser for den valgte dagen. Bruk dette for å enkelt legge til et forhåndskonfigurert diagram til dashboardet ditt. YAML vil bruke get_chartdata-tjenesten for data.", + "description": "⚠️ VIKTIG: Denne tjenesten genererer en GRUNNLEGGENDE EKSEMPEL-konfigurasjon for ApexCharts-kort som et utgangspunkt. Det er IKKE en komplett løsning for alle ApexCharts-funksjoner. Denne integrasjonen er primært en DATALEVERANDØR. Den genererte YAML-en demonstrerer hvordan du bruker `get_chartdata`-tjenesten for å hente prisdata. På grunn av den segmenterte naturen til våre data (forskjellige tidsperioder per serie) og bruken av Home Assistants service-API i stedet for entitetsattributter, er mange avanserte ApexCharts-funksjoner (som in_header, visse transformasjoner) ikke kompatible eller krever manuell tilpasning. Du er velkommen til å tilpasse den genererte YAML for dine spesifikke behov, men vær oppmerksom på at omfattende ApexCharts-konfigurasjonsstøtte er utenfor rammen av denne integrasjonen. Bidrag fra fellesskapet med forbedrede konfigurasjoner er alltid velkomne - hvis du finner en bedre oppsett som fungerer, vennligst del det slik at alle kan dra nytte av det! For direkte datatilgang for å bygge dine egne diagrammer, bruk `get_chartdata`-tjenesten i stedet.", "fields": { "entry_id": { "name": "Oppførings-ID", diff --git a/custom_components/tibber_prices/translations/nl.json b/custom_components/tibber_prices/translations/nl.json index d62d96f..1a001a0 100644 --- a/custom_components/tibber_prices/translations/nl.json +++ b/custom_components/tibber_prices/translations/nl.json @@ -787,7 +787,7 @@ }, "get_apexcharts_yaml": { "name": "ApexCharts-kaart YAML ophalen", - "description": "Retourneert een kant-en-klaar YAML-fragment voor een ApexCharts-kaart die Tibber-prijzen voor de geselecteerde dag visualiseert. Gebruik dit om eenvoudig een vooraf geconfigureerd diagram aan je dashboard toe te voegen. De YAML gebruikt de get_chartdata-service voor gegevens.", + "description": "⚠️ BELANGRIJK: Deze service genereert een BASALE VOORBEELD-configuratie voor ApexCharts-kaart als startpunt. Het is GEEN complete oplossing voor alle ApexCharts-functies. Deze integratie is primair een GEGEVENSLEVERANCIER. De gegenereerde YAML demonstreert hoe je de `get_chartdata`-service gebruikt om prijsgegevens op te halen. Vanwege de gesegmenteerde aard van onze gegevens (verschillende tijdsperioden per serie) en het gebruik van Home Assistant's service-API in plaats van entiteitsattributen, zijn veel geavanceerde ApexCharts-functies (zoals in_header, bepaalde transformaties) niet compatibel of vereisen handmatige aanpassing. Je bent welkom om de gegenereerde YAML aan te passen voor jouw specifieke behoeften, maar begrijp alsjeblieft dat uitgebreide ApexCharts-configuratieondersteuning buiten het bereik van deze integratie valt. Bijdragen van de gemeenschap met verbeterde configuraties zijn altijd welkom - als je een betere setup vindt die werkt, deel het dan alsjeblieft zodat iedereen ervan kan profiteren! Voor directe gegevenstoegang om je eigen grafieken te bouwen, gebruik in plaats daarvan de `get_chartdata`-service.", "fields": { "entry_id": { "name": "Invoer-ID", diff --git a/custom_components/tibber_prices/translations/sv.json b/custom_components/tibber_prices/translations/sv.json index fc97f1b..ccd57fa 100644 --- a/custom_components/tibber_prices/translations/sv.json +++ b/custom_components/tibber_prices/translations/sv.json @@ -787,7 +787,7 @@ }, "get_apexcharts_yaml": { "name": "Hämta ApexCharts-kort YAML", - "description": "Returnerar ett färdigt YAML-utklipp för ett ApexCharts-kort som visualiserar Tibber-priser för den valda dagen. Använd detta för att enkelt lägga till ett förkonfigurerat diagram till din instrumentpanel. YAML kommer att använda get_chartdata-tjänsten för data.", + "description": "⚠️ VIKTIGT: Denna tjänst genererar en GRUNDLÄGGANDE EXEMPEL-konfiguration för ApexCharts-kort som utgångspunkt. Det är INTE en komplett lösning för alla ApexCharts-funktioner. Denna integration är i första hand en DATALEVERANTÖR. Den genererade YAML demonstrerar hur du använder `get_chartdata`-tjänsten för att hämta prisdata. På grund av den segmenterade naturen hos våra data (olika tidsperioder per serie) och användningen av Home Assistants service-API istället för entitetsattribut, är många avancerade ApexCharts-funktioner (som in_header, vissa transformationer) inte kompatibla eller kräver manuell anpassning. Du är välkommen att anpassa den genererade YAML för dina specifika behov, men förstå att omfattande ApexCharts-konfigurationsstöd ligger utanför ramen för denna integration. Gemenskapsbidrag med förbättrade konfigurationer är alltid uppskattade - om du hittar en bättre inställning som fungerar, dela den gärna så att alla kan dra nytta av det! För direkt dataåtkomst för att bygga dina egna diagram, använd `get_chartdata`-tjänsten istället.", "fields": { "entry_id": { "name": "Post-ID", diff --git a/docs/user/automation-examples.md b/docs/user/automation-examples.md index 8ab71f8..ecde2c4 100644 --- a/docs/user/automation-examples.md +++ b/docs/user/automation-examples.md @@ -241,7 +241,13 @@ Coming soon... ## ApexCharts Cards -The `tibber_prices.get_apexcharts_yaml` service generates complete ApexCharts card configurations for visualizing electricity prices. +> ⚠️ **IMPORTANT:** The `tibber_prices.get_apexcharts_yaml` service generates a **basic example configuration** as a starting point. It is NOT a complete solution for all ApexCharts features. +> +> This integration is primarily a **data provider**. Due to technical limitations (segmented time periods, service API usage), many advanced ApexCharts features require manual customization or may not be compatible. +> +> **For advanced customization:** Use the `get_chartdata` service directly to build charts tailored to your specific needs. Community contributions with improved configurations are welcome! + +The `tibber_prices.get_apexcharts_yaml` service generates basic ApexCharts card configuration examples for visualizing electricity prices. ### Prerequisites diff --git a/docs/user/services.md b/docs/user/services.md index fac441f..29b05d9 100644 --- a/docs/user/services.md +++ b/docs/user/services.md @@ -110,7 +110,15 @@ For detailed parameter descriptions, see the service definition in **Developer T ### tibber_prices.get_apexcharts_yaml -**Purpose:** Generates complete ApexCharts card YAML configuration for visualizing electricity prices. +> ⚠️ **IMPORTANT:** This service generates a **basic example configuration** as a starting point, NOT a complete solution for all ApexCharts features. +> +> This integration is primarily a **data provider**. The generated YAML demonstrates how to use the `get_chartdata` service to fetch price data. Due to the segmented nature of our data (different time periods per series) and the use of Home Assistant's service API instead of entity attributes, many advanced ApexCharts features (like `in_header`, certain transformations) are **not compatible** or require manual customization. +> +> **You are welcome to customize** the generated YAML for your specific needs, but comprehensive ApexCharts configuration support is beyond the scope of this integration. Community contributions with improved configurations are always appreciated! +> +> **For custom solutions:** Use the `get_chartdata` service directly to build your own charts with full control over the data format and visualization. + +**Purpose:** Generates a basic ApexCharts card YAML configuration example for visualizing electricity prices. **Prerequisites:** - [ApexCharts Card](https://github.com/RomRider/apexcharts-card) (required for all configurations)