PopupAlert

Benötigt: Symcon >= 5.0

Enthält das Konfigurationsformular dieses Element, so wird es beim Laden der Konfigurationsseite geöffnet. Nachdem das Popup geschlossen wurde, ist es zusätzlich möglich dies mithilfe von Dynamik (visible auf true) erneut zu öffnen.

Allgemeine Parameter

Parameter für popup

Parameter für pages

Das Feld pages beinhaltet eine Liste von Objekten, welche jeweils eine Seite beschreiben. Enthält die Liste mindestens zwei Seiten, so werden bei den Buttons ganz rechts zusätzlich "Zurück" und "Weiter" bzw. "OK" angezeigt, worüber die Seiten gewechselt werden können. Der Schließen-Button ist dann standardmäßig mit "Abbrechen" beschriftet. Für den zweiten Button wird "Weiter" angezeigt, falls die über nextPage bestimmte Seite existiert, ansonsten "OK", welches das Popup schließt. "Zurück" ist aktiv, falls die aktuelle Seite über "Weiter" erreicht wurde. Wurde dabei eine Seite verlassen, welche ein Skript für "onConfirm", aber keines für "onUndo" definiert hat, so ist "Zurück" deaktiviert und keine der vorherigen Seiten kann wieder erreicht werden. Enthält die Liste nur eine Seite, so wird diese ohne "Zurück" und "Weiter" wie ein reguläres Popup angezeigt. Anwendungsfälle, der genaue Ablauf und Beispiele sind im Abschnitt Wizard sowie ausführlich beim PopupButton beschrieben. Jedes dieser Objekte kann die folgenden Parameter nutzen:

Die Parameter closeCaption und width gelten immer für das gesamte Popup und können nicht je Seite festgelegt werden.

Parameter für buttons

Wizard

Über den Parameter pages wird aus dem Popup ein Wizard (Assistent), welcher den Benutzer Schritt für Schritt durch einen Vorgang führt (ab Symcon 9.1). Die Seiten verhalten sich beim PopupAlert genauso wie beim PopupButton. Anwendungsfälle, der Ablauf beim Weiter, Zurück und Abbrechen, die verfügbaren Variablen, das Steuern des Seitenwechsels, Hinweise und weitere Beispiele sind beim PopupButton beschrieben.

Im Unterschied zum PopupButton wird der PopupAlert ohne Klick des Benutzers geöffnet:

• Ist visible beim Laden des Konfigurationsformulars true, so wird der Wizard sofort geöffnet. Setzt GetConfigurationForm visible abhängig von der Konfiguration, so erscheint der Wizard genau dann, wenn die Instanz noch eingerichtet werden muss.
• Das Modul kann den Wizard jederzeit per UpdateFormField über visible öffnen, z.B. über einen Button "Einrichtung starten", und mit false schließen. Der Wizard beginnt dabei jeweils auf der Seite, die über initialPage bzw. popup.initialPage festgelegt ist. Das gilt auch, wenn der Wizard bereits geöffnet ist: Setzt das Modul zuerst popup.initialPage und anschließend visible auf true, so wechselt der Wizard auf diese Seite, z.B. per $this->UpdateFormField('SetupWizard', 'popup.initialPage', 'settings') und $this->UpdateFormField('SetupWizard', 'visible', true). Die Eingaben bleiben erhalten, "Zurück" ist danach deaktiviert.

Einrichtungsassistent

Ein bewährtes Muster für die Einrichtung eines Moduls:

• Der Wizard steht unter actions und wird in GetConfigurationForm sichtbar geschaltet, solange eine benötigte Eigenschaft nicht gesetzt ist.
• Die erste Seite begrüßt den Benutzer und fragt über eine RadioButtonGroup, wie die Einrichtung erfolgen soll. Die Werte der Optionen entsprechen den Namen der folgenden Seiten, sodass nextPage die Auswahl direkt zurückgeben kann. Eine Option erlaubt es, die Einrichtung zu überspringen.
• Eine Seite zeigt das Ergebnis einer Suche an. Ihre items werden per PHP-Code vom Modul erzeugt, sodass die Suche bei jedem Wechsel auf die Seite erneut ausgeführt wird.
• Das onConfirm der letzten Einstellungsseite schreibt die Werte per UpdateFormField in die Felder des Konfigurationsformulars. Der Benutzer sieht das Ergebnis und speichert es mit "Änderungen übernehmen". Das onUndo setzt die Felder wieder auf die gespeicherten Werte zurück.
• Am Ende der Liste stehen Abschlussseiten, welche über ihren Namen angesprungen werden: eine Zusammenfassung und ein Hinweis beim Überspringen. Die Zusammenfassung beendet den Wizard per "nextPage": -1, da die Seite zum Überspringen noch folgt.
• Ein Button unter actions öffnet den Wizard erneut.

Beispiel: Einrichtungsassistent für ein Gerät im Netzwerk. Solange die Eigenschaft Host leer ist, öffnet sich der Wizard beim Öffnen der Instanzkonfiguration.

// Beispiel: form.json
{
    "elements": [
        { "type": "ValidationTextBox", "name": "Host", "caption": "Host" },
        { "type": "NumberSpinner", "name": "Interval", "caption": "Aktualisierungsintervall", "suffix": "Sekunden", "minimum": 10 }
    ],
    "actions": [
        {
            "type": "Button",
            "caption": "Einrichtung starten",
            "onClick": "SET_UIOpenWizard($id);"
        },
        {
            "type": "PopupAlert",
            "name": "SetupWizard",
            "visible": false,
            "popup": {
                "caption": "Einrichtung",
                "width": "600px",
                "pages": [
                    {
                        "caption": "Willkommen",
                        "items": [
                            { "type": "Label", "caption": "Dieser Assistent richtet die Verbindung zum Gerät ein." },
                            {
                                "type": "RadioButtonGroup",
                                "name": "WizardStart",
                                "caption": "Wie soll das Gerät gefunden werden?",
                                "value": "search",
                                "options": [
                                    { "caption": "Im Netzwerk suchen", "value": "search" },
                                    { "caption": "Adresse manuell eingeben", "value": "manual" },
                                    { "caption": "Einrichtung überspringen", "value": "skip" }
                                ]
                            }
                        ],
                        "nextPage": "return $WizardStart;"
                    },
                    {
                        "name": "search",
                        "caption": "Gefundene Geräte",
                        "items": "return json_decode(SET_UIGetSearchItems($id), true);",
                        "validate": "if (($WizardFoundHost ?? '') == '') { return 'Bitte ein Gerät auswählen'; }",
                        "nextPage": "settings"
                    },
                    {
                        "name": "manual",
                        "caption": "Adresse",
                        "items": [
                            { "type": "ValidationTextBox", "name": "WizardManualHost", "caption": "Host", "validate": "^[a-zA-Z0-9.:-]+$" }
                        ]
                    },
                    {
                        "name": "settings",
                        "caption": "Einstellungen",
                        "items": [
                            { "type": "NumberSpinner", "name": "WizardInterval", "caption": "Aktualisierungsintervall", "suffix": "Sekunden", "value": 60 }
                        ],
                        "validate": "if ($WizardInterval < 10) { return 'Das Intervall muss mindestens 10 Sekunden betragen'; }",
                        "onConfirm": "SET_UIApply($id, ($WizardStart == 'search') ? ($WizardFoundHost ?? '') : $WizardManualHost, $WizardInterval);",
                        "onUndo": "SET_UIRevert($id);",
                        "nextPage": "summary"
                    },
                    {
                        "name": "summary",
                        "caption": "Fertig",
                        "items": [
                            { "type": "Label", "caption": "Die Einstellungen wurden in das Konfigurationsformular eingetragen. Bitte mit \"Änderungen übernehmen\" speichern." }
                        ],
                        "nextPage": -1
                    },
                    {
                        "name": "skip",
                        "caption": "Einrichtung übersprungen",
                        "items": [
                            { "type": "Label", "caption": "Ohne Host ist die Instanz nicht funktionsfähig. Die Einrichtung kann jederzeit über \"Einrichtung starten\" fortgesetzt werden." }
                        ]
                    }
                ]
            }
        }
    ]
}

// Beispiel: module.php
<?php

declare(strict_types=1);

class SetupWizardDevice extends IPSModule
{
    public function Create()
    {
        //Never delete this line!
        parent::Create();

        $this->RegisterPropertyString('Host', '');
        $this->RegisterPropertyInteger('Interval', 60);
    }

    public function GetConfigurationForm()
    {
        $form = json_decode(file_get_contents(__DIR__ . '/form.json'), true);
        // Der Wizard öffnet sich automatisch, solange die Instanz nicht eingerichtet ist
        $form['actions'][1]['visible'] = ($this->ReadPropertyString('Host') == '');
        return json_encode($form);
    }

    // Button "Einrichtung starten"
    public function UIOpenWizard()
    {
        $this->UpdateFormField('SetupWizard', 'visible', true);
    }

    // items der Seite "search": Wird bei jedem Wechsel auf die Seite ausgeführt
    public function UIGetSearchItems(): string
    {
        // In einem echten Modul werden die Geräte hier z.B. per DNS-SD gesucht
        $devices = ['192.168.1.20' => 'Gerät im Wohnzimmer', '192.168.1.21' => 'Gerät im Keller'];

        if (count($devices) == 0) {
            return json_encode([
                ['type' => 'Label', 'caption' => 'Es wurde kein Gerät gefunden. Bitte zurückgehen und die Adresse manuell eingeben.']
            ]);
        }
        $options = [];
        foreach ($devices as $host => $name) {
            $options[] = ['caption' => $name . ' (' . $host . ')', 'value' => $host];
        }
        return json_encode([
            ['type' => 'Select', 'name' => 'WizardFoundHost', 'caption' => 'Gerät', 'options' => $options, 'value' => $options[0]['value']]
        ]);
    }

    // onConfirm der Seite "settings": Trägt die Werte in das Konfigurationsformular ein
    public function UIApply(string $Host, int $Interval)
    {
        $this->UpdateFormField('Host', 'value', $Host);
        $this->UpdateFormField('Interval', 'value', $Interval);
    }

    // onUndo der Seite "settings": Stellt die gespeicherten Werte wieder her
    public function UIRevert()
    {
        $this->UpdateFormField('Host', 'value', $this->ReadPropertyString('Host'));
        $this->UpdateFormField('Interval', 'value', $this->ReadPropertyInteger('Interval'));
    }
}

Beispiel

{
    "type": "PopupAlert",
    "popup": {
        "closeCaption": "I understand",
        "items": [
            {
               "type": "Label",
               "caption": "Be careful when configuring this instance. Even small changes can have significant impact!"
            }
        ]
    }
},
{
    "type": "PopupAlert",
    "popup": {
        "items": [
            {
                 "type": "SelectVariable",
                 "name": "VariableActionTest",
                 "caption": "Some Action Variable"
            }
        ]
    }
},
{
    "type": "PopupAlert",
    "popup": {
        "caption": "Ein Titel, der nie gesehen wird, da jede Seite ihn überschreibt",
        "closeCaption": "Schließe Dialog",
        "items": [
            {
                "type": "Label",
                "caption": "Dieses Element wird nie gesehen, da jede Seite ihre eigenen items hat"
            }
        ],
        "pages": [
            {
                "caption": "Start",
                "items": [
                    {
                        "type": "Label",
                        "caption": "Nächste Seite: Auswahl"
                    }
                ],
                "nextPage": 2
            },
            {
                "caption": "Nie sichtbar",
                "items": [
                    {
                        "type": "Label",
                        "caption": "Diese Seite wird nie angezeigt, da die Startseite direkt auf die Seite mit Index 2 springt, die Auswahl"
                    }
                ]
            },
            {
                "caption": "Auswahl",
                "items": [
                    {
                        "type": "Select",
                        "name": "NextPage",
                        "options": [
                            {"value": "page1", "caption": "Gehe zu Seite 1"},
                            {"value": "page2", "caption": "Gehe zu Seite 2"},
                            {"value": "close", "caption": "Fertig, schließen"}
                        ],
                        "caption": "Wähle nächste Seite"
                    }
                ],
                "nextPage": "return $NextPage;"
            },
            {
                "name": "page1",
                "caption": "Seite 1",
                "items": [
                    {
                        "type": "Label",
                        "caption": "Dies ist Seite 1 mit 'Undo'"
                    }
                ],
                "onUndo": "echo 'Seite 1 rückgängig machen';",
                "onConfirm": "echo 'Seite 1 bestätigen';"
            },
            {
                "name": "page2",
                "caption": "Seite 2",
                "items": [
                    {
                        "type": "Label",
                        "caption": "Dies ist Seite 2, es gibt kein 'Undo'. Dies ist auch die letzte Seite des Wizards."
                    }
                ],
                "onConfirm": "echo 'Seite 2 bestätigen';"
            }
        ]
    }
}