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.

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 …

… und nach einem Klick auf Weiter die Angaben zur 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.

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

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.

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.

Das Element wird korrekt formatiert ins JSON eingefügt:

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:

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).

Übersetzungen hinzufügen

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

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

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.

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.

Splitter zuweisen

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

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.

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 .