Suche

    Symcon Modul Helfer

    Der Symcon Modul Helfer ist eine Erweiterung für Visual Studio Code, die das Entwickeln von Symcon-Modulen und -Bibliotheken deutlich komfortabler macht. Sie vereint Projekt-Assistenten, Code-Generator, Formular-Editor und Live-Vorschau in einer Oberfläche. Mit wenigen Klicks entsteht eine komplette Bibliothek oder ein neues Modul, bestehende Projekte lassen sich pflegen und werden automatisch mit GUIDs, Build-Informationen und Dokumentation versorgt.

    Visual Studio Code mit geöffneter module.html und Live-Vorschau einer Kachel
    Live-Vorschau einer Kachelvisualisierung direkt in VS Code

    Wie alles begann

    Angefangen hat alles mit einer Diskussion im Forum über die Konfiguration von Modulen . Das Fazit in kurzen Worten: Den Komfort der Konfigurationsformulare möchte man weiter nutzen, aber die Unterstützung für Entwickler beim Erstellen ist verbesserungswürdig.

    Ein Programm, das Formulare rein visuell zusammenklickt, wäre ein Projekt von Wochen oder Monaten gewesen. Also habe ich mit einer Zwischenlösung begonnen: einer VS Code Extension namens Forminator, die beim Schreiben der form.json hilft und das ständige Nachschlagen in der Dokumentation erspart. Aus diesem kleinen Formular-Helfer ist inzwischen ein umfassendes Werkzeug für den gesamten Entwicklungsablauf geworden, und so hat er auch seinen neuen Namen bekommen.

    Die Funktionen im Überblick

    Assistenten und Generatoren

    • Bibliothek-Assistent: legt ein neues Symcon-Bibliotheksprojekt an
    • Modul-Assistent: fügt einer bestehenden Bibliothek ein neues Modul hinzu
    • Eigene Vorlagen: ein eigener Vorlagen-Ordner ist konfigurierbar
    • README-Pflege: die Modulliste in der Dokumentation wird beim Hinzufügen eines Moduls automatisch erweitert
    • Prüfungen und GUIDs: Felder werden validiert, GUIDs automatisch vergeben
    • Kachelvisualisierung: ein bestehendes Modul lässt sich nachträglich um die Funktionen für die Tile Visu erweitern (mit module.html-Vorlage)

    Formular-Editor

    • Alle Standard-Elemente des Symcon PHP-SDK per Klick einfügen
    • Automatisch erzeugte, korrekt formatierte JSON-Snippets
    • Sidebar-Editor, der alle Eigenschaften eines Elements mit ihren Standardwerten anzeigt

    Live-Vorschau

    • Echtzeit-Vorschau der Kachelvisualisierung (HTML, JSON, Design, Größe) in einem eingebetteten Fenster
    • Einstellungen wie Design, Breite und Höhe werden pro Arbeitsbereich gespeichert
    • Vorschau-Daten (JSON) speichern, laden und direkt an die Kachel senden

    Hilfsfunktionen

    • Build-Informationen in der library.json aktualisieren (Buildnummer und Datum)
    • Splitter zuweisen: gültige GUIDs in die module.json eintragen
    • Übersetzungen aus der form.json in die locale.json übernehmen
    • RegisterProperty-Aufrufe für alle Eigenschaften des Formulars in Create() erzeugen

    Installation

    Die Erweiterung gibt es kostenlos im Visual Studio Marketplace :

    1. Visual Studio Code öffnen
    2. Die Erweiterungen aufrufen (Strg + Umschalt + X)
    3. Nach „Symcon Modul Helfer“ suchen
    4. Auf Installieren klicken

    Alternativ lässt sich eine .vsix-Datei manuell über den Befehl Extensions: Install from VSIX... installieren.

    So funktioniert’s

    Fast alle Funktionen erreicht man über die Befehlspalette (Strg + Umschalt + P) oder das Kontextmenü mit der rechten Maustaste. Welche Befehle angeboten werden, hängt von der gerade geöffneten Datei ab.

    Neue Bibliothek anlegen

    In der Befehlspalette „Neues Projekt für eine Modulbibliothek erstellen (über Assistent)“ wählen. Der Assistent fragt zuerst die Projektdaten ab …

    Assistent für ein neues Projekt
    Schritt 1: Projektdaten

    … und nach einem Klick auf Weiter die Angaben zur Bibliothek.

    Angaben zur neuen Bibliothek
    Schritt 2: Bibliothek

    Mit Erstellen und öffnen wird das Projekt angelegt und VS Code öffnet es automatisch.

    Neues Modul hinzufügen

    In einem bestehenden Bibliotheksprojekt startet „Neues Modul hinzufügen (über Assistent)“ den Modul-Assistenten. Die GUID ist bereits vergeben, Pflichtfelder wie Name, Präfix und URL werden direkt geprüft.

    Assistent für ein neues Modul mit GUID, Name, Typ, Datenfluss und Präfix
    Modul-Assistent mit Prüfung der Pflichtfelder

    Auf der nächsten Seite folgen die Einstellungen für die Programmierung. Ein Klick auf Hinzufügen, und das Modul ist Teil der Bibliothek.

    Einstellungen für die Programmierung des Moduls
    Einstellungen für die Programmierung

    Formular-Elemente einfügen

    Das Herzstück der Erweiterung: Sobald eine form.json geöffnet ist, erscheint in der Seitenleiste die Übersicht aller Formular-Elemente.

    Seitenleiste mit allen Formular-Elementen
    Alle Formular-Elemente auf einen Blick
    1. Den Cursor an die Stelle im JSON setzen, an der das neue Element stehen soll, zum Beispiel hinter die schließende Klammer des vorherigen Elements.
    2. In der Seitenleiste das gewünschte Element auswählen.
    3. Darunter erscheint ein Formular mit allen Eigenschaften und ihren Standardwerten. Bei komplexeren Elementen wie einer Liste kann man auf Wunsch Beispieldaten einsetzen lassen.
    4. Die Eigenschaften anpassen und auf Element einfügen klicken.
    Eigenschaften eines Label-Elements in der Seitenleiste
    Eigenschaften am Beispiel Label

    Das Element wird korrekt formatiert ins JSON eingefügt:

    Eingefügtes Element in der form.json
    Ergebnis in der form.json

    Live-Vorschau der Kachelvisualisierung

    Für Module mit Kachelvisualisierung zeigt der Helfer die module.html direkt in VS Code an. Zuerst in den Einstellungen der Erweiterung die Vorschau konfigurieren:

    Einstellungen für die Live-Vorschau
    Einstellungen der Live-Vorschau

    Dann die module.html öffnen und die Vorschau über die Befehlspalette oder das Kontextmenü starten. Design, Höhe und Breite der Kachel lassen sich in der Vorschau umstellen, die Testdaten werden als JSON eingegeben und gespeichert (siehe Bild oben).

    Kontextmenü mit dem Befehl für die Vorschau
    Vorschau über das Kontextmenü starten

    Übersetzungen hinzufügen

    In der form.json den zu übersetzenden Text markieren und im Kontextmenü „Übersetzung zur locale.json hinzufügen“ wählen.

    Kontextmenü mit dem Befehl für Übersetzungen
    Übersetzung über das Kontextmenü

    Nach Eingabe der Übersetzung landet eine neue Zeile in der locale.json.

    Eingabefeld für die Übersetzung
    Eingabe der Übersetzung

    RegisterProperty-Aufrufe erzeugen

    In der module.php den Befehl „Füge RegisterProperty-Aufrufe in Create() ein.“ aufrufen. Für alle in der form.json definierten Eigenschaften wird ein passender RegisterProperty-Aufruf in die Create()-Methode geschrieben.

    Befehlspalette mit dem Befehl für RegisterProperty
    RegisterProperty-Aufrufe per Befehl

    Build-Informationen aktualisieren

    In der library.json den Befehl „Build-Informationen aktualisieren“ wählen. Auf Wunsch lässt sich ein Versatz in Tagen angeben, falls nicht das heutige Datum verwendet werden soll. Danach haben build und date aktuelle Werte.

    Befehl zum Aktualisieren der Build-Informationen
    Build-Informationen aktualisieren

    Splitter zuweisen

    In der module.json mit „Splitter zu Modul zuweisen“ einen der angebotenen Splitter auswählen. Die passenden GUIDs werden automatisch eingetragen.

    Auswahlliste der verfügbaren Splitter
    Auswahl des Splitters

    Kachelvisualisierung anlegen

    Für ein Modul, das noch keine module.html hat, den Modul-Ordner auswählen und „Kachelvisualisierung anlegen“ aufrufen. Die nötigen Funktionen werden der module.php hinzugefügt und eine neue module.html wird erzeugt.

    Kontextmenü mit dem Befehl Kachelvisualisierung anlegen
    Kachelvisualisierung nachträglich anlegen

    Für wen ist die Erweiterung?

    Der Modul Helfer richtet sich an alle, die eigene Module für Symcon mit dem PHP-SDK entwickeln. Einsteiger profitieren von den Assistenten und davon, dass alle Eigenschaften eines Formular-Elements samt Standardwerten sichtbar sind. Erfahrene Entwickler sparen sich wiederkehrende Handgriffe wie GUIDs, Build-Nummern, Übersetzungen und RegisterProperty-Aufrufe.

    Feedback

    Anregungen, Fehlermeldungen und Wünsche sind jederzeit willkommen, entweder als Issue im GitHub-Repository oder im Thread im Symcon-Forum .

    Die Erweiterung ist für nicht-kommerzielle Zwecke kostenlos und steht unter der Lizenz CC BY-NC-SA 4.0 .