Development – Step by Step zum eigenen Module

Ausgangslage und Ziel

Am Beginn jeder Modul Entwicklung sollte man einmal kurz die Ausgangslage und die Ziele beschreiben.

Ziel

Ziel ist es ein Modul zu schreiben, das die täglichen Dämmerungszeiten berechnet und grafisch anzeigt.

  • Berechnung der täglichen Dämmerungszeiten
  • Berechnung der Zeiten mit einem oberen und unteren Limit
  • Grafische Visualisierung
  • Anlegen von Variablen tägliche Aktualisierung mit berechneten Zeiten
  • Generierung von Timern und Aufruf von Callback Methoden
  • Autom. Anlegen von WebFront und Mobile GUI

Voraussetzungen

Keine Voraussetzungen

Das Modul kann von Jedem installiert werden, es benötigt keinerlei Voraussetzungen

IPSTwillight_Unlimited

Installation

Auswahl des Modul Namens Pfades in der Library

Als erstes erfolgt die Auswahl des Pfades, wo das Modul zukünftig in der IPSLibrary zu finden ist. Da es sich hier um ein allgemeines Modul handelt und es in den Überbegriff Wetter fällt wurde folgende Location gewählt: IPSLibrary.app.module.weather.IPSTwilight

Benannt wird das Module mit: IPSTwilight 

Schritt 1: Anlegen der benötigten Scripte

Jedes Modul benötigt 3 Installations Scripte und 1 oder mehrere Applikations Scripte. Jedes dieser Files liegt in vordefinierten Ordnern, die sich durch den gewählten Modul Pfad ergeben.

Installations Scripte

Diese Scripts sind für die komplette Installation bzw. Deinstallation verantwortlich. Die Namen der Files sind fix vorgegeben und setzen sich aus den Modul Namen und dem jeweiligen Suffix zusammen.

  • …\IPSLibrary\install\DownloadListFiles\IPSTwilight_Filelist.ini
  • …\IPSLibrary\install\InstallationScripts\IPSTwilight_Installation.ips.php
  • …\IPSLibrary\install\InitializationFiles\default\IPSTwilight.ini

IPSTwilight_Filelist.ini enthält eine Liste aller Files, die für das Modul benötigt werden
IPSTwilight_Installation.ips.php enthält den Code, der die benötigten Objekte (Variablen, Instanzen, Timer) und die GUIs anlegt.
IPSTwilight.ini enthält diverse Initialisierungs Parameter, mit denen die Generierung des Webfronts gesteuert wird. Dieses File wird beim erstmaligen Laden des Modules in das „User“ Verzeichnis (…\IPSLibrary\install.InitializationFiles\) kopiert, Änderungen müssen vom Entwickler also immer in beiden Files vorgenommen werden.

Es ist auch zu bedenken, dass nachträgliche Änderungen an den „Default“ Files (nachdem das Modul bereits in die Library gestellt wurde), bei einem Update nicht automatisch auf bestehende Installationen ausgerollt wird, da diese Files nach dem erstmaligen Laden bereits kopiert werden und danach nicht mehr überschrieben werden. 

Modul Scripte

Der Name der eigentlichen Modul Scripts kann frei gewählt werden, der Modul Name als Prefix hat sich aber auch hier bewährt.

Folgende Files werden für das IPSTwilight Modul noch benötigt:

  • …\IPSLibrary\app\modules\weather\IPSTwilight\IPSTwilight.ips.php
  • …\IPSLibrary\config\modules\weather\IPSTwilight\default\IPSTwilight_Configuration.inc.php
  • …\IPSLibrary\config\modules\weather\IPSTwilight\default\IPSTwilight_Custom.inc.php

IPSTwilight.ips.php enthält die eigentliche Programm Logik, die die Dämmerungszeiten berechnet, Variablen aktualisiert, Grafiken generiert und die Timer neu erstellt.
IPSTwilight_Configuration.inc.php enthält einige Konfigurations Parameter, um die Berechnung der Zeiten auf den Wohnort anzupassen.
IPSTwilight_Custom.inc.php enhält Callback Methoden, diese werden von den generierten Timern aufgerufen und bieten dem User die Möglichkeit seinen eigenen Code zu platzieren.

Konfigurations und Custom File liegen im default Verzeichnis. Beim erstmaligen Laden des Modules werden die Files in den normalen User Ordner (…\IPSLibrary\config\modules\weather\IPSTwilight\) kopiert, wo sie der User ändern kann. Das heißt aber für den Entwickler, dass er Änderungen auch in den „Default“ Files nachziehen muss. 

Schritt 2: DownloadList File erstellen

Im 2. Schritt wird der Inhalt des IPSTwilight_Filelist.ini Files erstellt:

Hier folgende Informationen abgelegt:

  • Namespace – „Namespace“ des Modules (Pfad in der IPSLibrary durch „::“ getrennt)
  • Version – Aktuelle Version des Modules
  • Liste der Files (Application, Config, WebFront und install)

Schritt 3: Erstmaliges Laden des Modules

Im nächsten Schritt können die Module bereits in IPS registriert werden, dazu werden sie in das lokale GIT Verzeichnis „deployed“ und von dort wieder geladen und dabei in IPS registriert.

Die übrigen Files können bei diesem Vorgang auch noch leer sein, einzig im _ListFile.ini müssen alle Files korrekt registriert sein.

Der Vorgang kann auch später jederzeit wiederholt werden, falls es sich herausstellt, dass noch ein zusätzliches File benötigt wird. 

Schritt 4: Implementieren der Programmlogik

Die komplette Programm Logik ist in diesem Falle im File IPSTwilight.ips.php beinhaltet, der Code zur Berechnung der Dämmerungszeiten ist nicht Teil des WIKI Artikels und braucht an dieser Stelle nicht näher erörtert werden.

Die Entwicklung von Programm Logik und Installations Script kann aber durchaus iterativ erfolgen. Dh: Anlegen diverser Variablen und Profile mit dem Installer, Schreiben und Ausführung von Application Code zur Befüllung der Variablen, Anlegen zusätzlicher Variablen, Implementieren von WebFront und Mobile GUI… 

Schritt 5: Initialisierungs File

Im Initialisierungs File können prinzipiell beliebige Parameter zur Installation des Modules abgelegt werden. Mit ihnen ist normalerweise eine Feinjustierung der Installation möglich.

Damit die Deinstallation von Modulen aber Ordnungsgemäß funktioniert ist es nötig, dass man sich bei der Generierung von WebFront und Mobile Front an einige Naming Conventions hält:

  • Ablegen der WebFront Parameter in Gruppe „WFC10“
  • „Path“ spezifiziert den Pfad für die WebFront Objekte, dort müssen alle zugehörigen Objekte (Links, Dummy Module) abgelegt sein
  • Item Name des verwendeten TabPane muss im Parameter „TabPaneItem“ abgelegt sein
  • Parameter „TabPaneExclusive“ spezifiziert ob das TabPane dem Modul exklusive zur Verfügung steht (und so bei der Deinstallation auch komplett gelöscht werden kann)
  • Verwendete Tab’s sollten mit Hilfe der Parameter „TabItem“ bzw. „TabItem1“ bis „TabItem10“ angelegt werden
  • Ablegen der Mobile Parameter in Gruppe „Mobile“
  • „Path“ spezifiziert den Pfad für die Mobile Objekte, dort müssen alle zugehörigen Objekte (Links, Dummy Module) abgelegt sein
  • Parameter „PathExclusive“ spezifiziert ob der Ordner dem Modul exklusive zur Verfügung steht (und so bei der Deinstallation auch komplett gelöscht werden kann)
  • Verwendete Objekte (Links, Kategorien, Dummy Instanzen) unter diesem Pfad müssen mit Hilfe der Parameter „Name“ bzw. „Name1“ bis „Name10“ angelegt werden (außer der Pfad steht dem Module ohnehin exklusive zur Verfügung)

Schritt 6: Installations Script

IPSModuleManager instanzieren

Dieser Teil ist optional, hat aber den Vorteil, dass man das Installations Script auch ohne IPSModulManager starten kann (speziell während der Entwicklung der Installation vorteilhaft). 

Versions Checks

Hier werden alle benötigten Module überprüft, die zur Installation benötigt werden. Das spezifizierte Modul muss in einer Version größer oder gleich der angegebenen Version vorhanden sein. 

Includes

Include der benötigten Files 

Einlesen der Initialisierungs Parameter

Einlesen der benötigten Parameter aus dem Initialisierungs File. Sollte kein spezieller WebFront Konfigurator angegeben sein, so wird mit GetWFCIdDefault() der erst beste gefundene genommen. 

Module Kategorien Erstellen

Ermitteln der benötigten IDs für app und data.

Der app Pfad (Program.IPSLibrary.app.modules.weather.IPSTwilight) ist bereits durch den Aufruf von ModuleLoad erzeugt worden und beinhaltet alle Scripte.

Der data Pfad (Program.IPSLibrary.data.modules.weather.IPSTwilight) wird durch den Aufruf den IPSModuleManager beim Aufruf der Funktion GetModuleCategoryID(‚data‘) angelegt. 

Installation der IPS Objekte

Dieser Teil erstellt alle benötigten Objekte in IP-Symcon. Die verwendeten Funktionen befinden sich alle im Script IPSInstaller.inc.php und sind dort detailiert beschrieben. 

Erster Run der Applikation

Durch das inkludieren des Applikations Scriptes wird nun ein erster Run gemacht.

Im Falle von IPSTwilight werden nun alle Variablen berechnet, die Grafiken erzeugt und die erforderlichen Timer erzeugt. 

Create WebFront GUI

Dieser Teil erzeuft das komplette WebFront: Zuerst wird durch die Variable $WFC10_Enabled überprüft, ob die Generierung des WebFronts aktiviert ist.

Es folgt die Generierung des Visualisierungs Ordners mit „CreateCategoryPath($WFC10_Path)“. Wichtig auch hier, dass alle Objecte unter diesem Object angelegt werden, damit die Deinstallation funktioniert.

Danach werden für die diversen SplitPanes Kategorien angelegt und darin diverse Links

Nun folgt der komplizierteste Teil – das Anlegen der eigentlichen WebFront Elemente. Im Prinzip läuft es aber genauso ab, wie im WebFront Konfigurator. Es werden SplitPanes und WebFront Kategorien angelegt und mit Hilfe der ItemIDs ineinander verschachtelt.

Am Ende werden alle WebFronts mit dem Befehl ReloadAllWebFronts neu geladen, damit die Änderungen auch sichtbar werden.

DevStepByStep_WebFront

Create Mobile GUI

Dieser Teil generiert die komplette Mobile GUI: Analog zum WebFront wird auch hier ein Ordner angelegt und darunter alle Elemente platziert.

Wichtig auch hier wieder, dass die ausgelesenen INI Parameter verwendet werden, damit auch eine Deinstallation wieder möglich ist. 

Dokumentation

Da die Dokumentation meistens zu kurz kommt, empfehle ich den Großteil der Dokumentation bereits während der Entwicklung des Modules zu machen.

Folgende Teile sollten dokumentiert sein:

  • Allgemeine Beschreibung des Modules – was kann es, was wird vorausgesetzt
  • Konfiguration – alle Konfigurations Parameter sollten detailiert beschrieben sein
  • Installation – kurze Beschreibung der Installation
  • API – falls vorhanden, sollte die API und deren Parameter beschrieben sein.
  • WebFront und Mobile GUI
  • Alle Files sollten einen Fileheader haben, der den Zweck beschreibt, den Filenamen und Author beinhaltet und auch eine Versionierung auflistet

Author, File und Version

Alle Dateien sollten einen kurzen Header haben, der den Author, den Filenamen und die Versions History beinhaltet:

Allgemeine Beschreibung

Beschreibung der Konfigurations Parameter

Jeder Konfigurations Parameter sollte eine kurz Beschreibung haben, die seinen Zweck beschreibt und den Impact einer Änderung.

WebFront und Mobile GUI

Mit “defgroup”, “ingroup” und “addtogroup” kann man in Doxygen eine Gruppierung erzeugen. Diese kann auch dazu benützt werden Abschnitt Visualisierung zu gestalten, in dem sich einige Screenshot befinden um dem User eine bessere Vorstellung vom Modul zu ermöglichen.

Screenshots sollten immer als Prefix den Modul Namen haben und sind im Ordner IPSLibrary.Docu.Screenshots zu platzieren.

File Header

Alle Files sollten einen kurzen Header haben, der auf die GPL License hinweist: