vis-jsontemplate

Überblick

Adapter zur Visualisierung von JSON-Daten und anderen Daten in Vis/Vis2. Die Datenausgabe lässt sich mithilfe eines Templatesystems anpassen. Die Templates können HTML, CSS und JavaScript einbinden. Das verwendete Templatesystem warejs Sie können die grundlegenden Funktionen hier im Online-Spielplatz ausprobieren: https://ionicabizau.github.io/ejs-playground

Das jsontemplate-Widget war zuvor in den Adaptern rssfeed (für vis1) und vis-2-widgets-ovarious verfügbar. Die Widgets werden in Kürze aus diesen Adaptern entfernt.

Inhaltsverzeichnis

• Installation
• Tags
  • Vis1-Widgets
  • Vis2-Widgets
• Todo
• Änderungsprotokoll
• Lizenz

Installation

Installieren Sie den Adapter wie gewohnt aus dem stabilen Repository. Wenn Sie neue Funktionen oder Fehlerbehebungen testen möchten, können Sie den Adapter auch aus dem Beta-Repository installieren. Informationen zu Funktionen und Neuigkeiten finden Sie im Thread „Test und Support“ für diesen Adapter im iobroker-Forum.

Nach der Installation sollte der Adapter im Adapterbereich des iobroker angezeigt werden. Manchmal sind die Änderungen nicht sichtbar, insbesondere bei webbasierten Änderungen (Widgets/Konfigurationsdialog). In diesem Fall muss möglicherweise folgender Befehl in der Kommandozeile ausgeführt werden:

iobroker upload jsontemplate

Im rechten Bereich der Adapterzeile kann mithilfe der Plus-Schaltfläche eine Instanz hinzugefügt werden.

Konfiguration

Dieser Adapter verfügt über keinen Konfigurationsdialog im Administrationsbereich.

vis und Widgets

Folgende Widgets existieren tatsächlich

• JSON Template - Sie können eine benutzerdefinierte Vorlage definieren, um beliebige JSON-Daten in vis anzuzeigen.

JSON-Vorlage

Mit diesem Widget lassen sich beliebige Datenpunkte mit JSON-Daten nach Wunsch darstellen. Die Darstellung erfolgt mithilfe eines Template-Formats, das sich als Kombination aus HTML-Code, JavaScript, CSS und speziellen Tags zur Steuerung der JSON-Attribute verstehen lässt. JSONTemplate unterstützt nun asynchrone Aufrufe mit `await`.

Einzelheiten zum Vorlagensystem finden Sie im Kapitel „Vorlagen basierend auf Beispielen“.

Verfügbare Datenobjekte in der Vorlage:

Die zusätzlichen Datenpunkte können über A) den Namen des Datenpunkts aufgerufen werden.

<%- dp["0_userdata.0.test"] %>
<%- dp["0_userdata.0.abc"] %>

B) Indexnummer des Datenpunkts (die Nummerierung beginnt immer mit 0)

<%- dp[Object.keys(dp)[0]] %>
<%- dp[Object.keys(dp)[1]] %>

C) Ein optionaler Variablenname, der für den Datenpunkt konfiguriert ist. Für einen Datenpunkt0_userdata.0.selectwrite , Variablennamedpwrite und Wertabc :

<%- dpwrite %>          <!-- 0_userdata.0.selectwrite -->
<%- dpwrite_value %>    <!-- abc -->
<%- dp[dpwrite] %>      <!-- abc -->

Beispielausgabe von Daten, Widgets und Stilen in der Vorlage

<%- JSON
    .stringify(style, null, 4)
    .replace(/\n/g, '<br>')
    .replace(/ /g, '&nbsp;'); %>

Im Fehlerfall wird dieser im Widget angezeigt und in der Browserkonsole (F12) ausgegeben.

Erweiterter Anwendungsfall

In den obigen Beispielen wurde nur die reine Ausgabe betrachtet. Die Vorlage kann nun auch mit HTML-Tags angereichert werden, um ein bestimmtes Layout zu erzielen. Hier ist ein Beispiel:

<h3>Output</h3>
<style>
    .mycssclassproperty {
        color: green;
    }
    .mycssclassdata {
        color: red;
    }
</style>
<% for (var prop in data.oneobject) { %>
<div>
    <span class="mycssclassproperty"><%- "data.oneobject." + prop + " = " %></span>
    <span class="mycssclassdata"><%- data.oneobject[prop] %></span>
</div>
<% } %>

Ergebnis:

    data.oneobject.attribute1 = 1
    data.oneobject.attribute2 = 2

(In Markdown sind Farben nicht sichtbar)

Weitere Anwendungsfälle

• Anwendungsfall: Asynchrone Aufrufe
• Anwendungsfall-Ladeskripte
• Aufgabenliste für Anwendungsfälle
• Anwendungsfall: öffentlicher Verkehr
• Anwendungsfall: einfaches Messgerät
• Anwendungsfall: GitHub-Issues und Pull Requests
• Anwendungsfall FRITZ!Box Anrufliste

Vorlagensystem

Sehr wichtiger Hinweis zur Verwendung in vis / vis-2

Geschweifte Klammern in CSS und JSON

Der Bindungsmechanismus in vis / vis-2 nutzt das Muster{ ... } Um Bindungsausdrücke in HTML zu erkennen, müssen geschweifte Klammern bei der Angabe von CSS oder JSON immer in separaten Zeilen stehen. Andernfalls wird der Inhalt des vis-Widgets überschrieben.undefined Die

Beispiel

#<%- widgetid %> { height: 100%; display: flex; flex-direction: column; overflow: hidden; }

muss wie folgt geschrieben werden:

#<%- widgetid %> {
    height: 100%; display: flex; flex-direction: column; overflow: hidden;
}

Verwendung von setInterval

Bitte nicht verwendensetInterval Da die Vorlage jedes Mal neu aufgerufen wird, wenn sich ein Datenpunkt ändert, werden alle bestehendensetInterval Anrufe können nicht ordnungsgemäß abgewickelt werden. Folglich kommt es zu einer zunehmenden Anzahl sich überschneidender Anrufe.setInterval Die Aufrufe häufen sich mit der Zeit; dies verbraucht Arbeitsspeicher und kann zu unvorhersehbaren Nebenwirkungen führen. Ein Neuladen der Seite kann dieses Problem zwar beheben, der Code sollte jedoch nicht auf diese Weise implementiert werden. Stattdessen sollten solche Szenarien mithilfe von … implementiert werden.setTimeout Die

Entwicklung von Vorlagen mit KI

Um die Erstellung von Vorlagen für alle zu vereinfachen, habe ich eine detaillierte Dokumentation mit Anleitungen und Beschreibungen vorbereitet:

• Englisch
• Deutsch

Tags

Das Templatesystem arbeitet mit bestimmten Tags. Die verwendeten Tags haben folgende Bedeutung:

Alles außerhalb dieser Tags wird unverändert angezeigt, oder, falls es sich um HTML handelt, als HTML interpretiert. Innerhalb der Vorlage stehen Ihnen zwei vordefinierte Variablen zur Verfügung.

Beispielobjekt

Für alle nachfolgenden Beispiele wird das folgende JSON verwendet.

{
    "onearray": ["one", "two"],
    "oneobject": {
        "attribute1": 1,
        "attribute2": 2
    },
    "onenumber": 123,
    "onetext": "onetwothree"
}

Attribute könnten wie folgt ausgegeben werden

Vorlage:

<%- data.onenumber %>
<%- data.onetext %>

Ergebnis:

    123 onetwothree

Auf Arrays kann über einen Index zugegriffen werden. Der Index beginnt immer mit 0. Es gibt jedoch auch sogenannte „Dummy-Arrays“, bei denen der Index nicht mit 0 beginnt oder sogar aus Text besteht. Hier gelten die Regeln für Objekte. Im obigen Beispiel wäre das:

Vorlage:

<%- data.onearray[0] %>
<%- data.onearray[1] %>

Ergebnis:

    one two

Wenn Sie versuchen, ein Array direkt ohne Index auszugeben, gibt die Vorlage alle Elemente durch Kommas getrennt aus.

Vorlage:

<%- data.onearray %>

Ergebnis:

    one,two

Arrays können auch aus einer Sammlung von Objekten bestehen. Das hier gezeigte Beispiel enthält nur ein einfaches Array. Ein Beispiel für Arrays mit Objekten wird später gegeben.

Vorlage:

<% for (var i = 0; i < data.onearray.length ; i++ ) { %>
<%- data.onearray[i] %>
<% } %>

Ergebnis:

    one two

Objekte können einzelne Attribute, Arrays oder wiederum Objekte enthalten. Das bedeutet, dass JSON-Daten beliebig tief verschachtelt werden können.

Attribute eines Objekts können mit der Punktnotation oder der Klammernotation angesprochen werden. Die Punktnotation funktioniert nur, wenn das Attribut bestimmten Namenskonventionen entspricht (erster Buchstabe, gefolgt von Zahlen, Buchstaben oder Unterstrichen). Die Klammernotation funktioniert auch für Attribute, die dieser Namenskonvention nicht entsprechen.

Punktnotation:

Vorlage:

<%- data.oneobject.attribute1 %>

Klammernotation:

Vorlage:

<%- data.oneobject["attribute1"] %>

Ergebnis für beide Beispiele:

    1

Iteriere über die Attribute eines Objekts

Vorlage:

<% for (var prop in data.oneobject) { %>
<%- "data.oneobject." + prop + " = " + data.oneobject[prop] %>
<% } %>

Ergebnis:

    data.oneobject.attribute1 = 1
    data.oneobject.attribute2 = 2

Entwicklung und Fehlersuche

Vis1-Widgets

• Installiere den Entwicklungsserver
• Starte den Entwicklungsserver mit der Option --noStart
• Installieren Sie beim ersten Start die zusätzlichen Adapter web und vis1.
• VS Code starten, Startkonfiguration "vis-1 Editor"
• Falls keine Widgets verfügbar sind, laden Sie den Adapter im Expertenmodus auf der Adapterseite hoch.
• Sie können nun in VS Code Haltepunkte in der Datei jsontemplate.js setzen.
• Wenn Sie etwas in der JS-Datei ändern, muss der Quellcode mit dem Befehl npm run build-vis1widgets in den dist-Ordner kompiliert werden.
• Der Entwicklungsserver lädt die geänderten Dateien auf iobroker hoch, aber für vis1 muss der Befehl iob visdebug ausgeführt werden, um die Widgets neu zu laden.
• Um weitere Einträge in en.json zu übersetzen, verwenden Sie den Befehl translate-widgets-vis1.

Vis2-Widgets

• Installiere den Entwicklungsserver
• Öffnen Sie ein neues VS Code-Fenster (2. Instanz).
• Klonen des Vis2-Repositorys
• Folgen Sie den Anweisungen in der Readme-Datei des vis2-Repositorys im Kapitel „Entwicklung und Debugging“. Sie müssen das Repository nicht forken. Wir benötigen lediglich eine laufende Instanz des vis2-Adapters.
• Starten Sie Vis 2 mit npm run start
• Zurück in der VS Code-Instanz dieses Adapters
• Starte den Entwicklungsserver mit der Option --noStart
• VS Code starten, Startkonfiguration "vis-2 Editor"
• Sie können nun in VS Code Haltepunkte in der Datei jsontemplate.js setzen.
• Wenn Sie eine Änderung vornehmen, müssen Sie nichts weiter tun, da Vite Hot Reload unterstützt. Manchmal ist es hilfreich, Vis2 mit F5 neu zu laden.
• Um weitere Einträge in en.json zu übersetzen, verwenden Sie den Befehl translate-widgets-vis2.

Todo

• tbd

Changelog

4.6.1 (2026-07-31)

• Improved error output.

4.6.0 (2026-07-30)

• some changes. see readme/below

Changes 2026-07-30

• add optional variable names to extra datapoints

4.5.0 (2026-07-29)

• some changes. see readme/below

Changes 2026-07-29

• repair widget rendering
• add search and fullscreen to ejs-edit for vis-2 widget
• improve ki documentation for regex expressions
• improve vis-2 ejs edit theme for dark mode

4.4.5 (2026-07-22)

• fix packages for vis-2

4.4.4 (2026-07-22)

• some changes. see readme/below

Changes 2026-07.22

• change documentation that in the template the widgetid is available and not widgetID
• add documentation for the usecase simple gauge
• add documentation for a responsive FRITZ!Box call list
• Due to an inconsistency between the vis1 and vis2 widgets, both widgetid and widgetID are now passed to the template.

License

MIT License

Copyright (c) 2021-2026 oweitman oweitman@gmx.de

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.