PopupAlert

Require: Symcon >= 5.0

If the configuration form contains this element, it will be opened when the configuration page is loaded. After the popup has been closed, it is also possible to open it again using dynamics (visible to true).

General Parameters

Parameters for popup

Parameters for pages

The pages field contains a list of objects, each describing a page. If the list contains at least two pages, the buttons on the far right additionally show "Previous" and "Next" or "OK", which can be used to switch between pages. The close button is then labeled "Cancel" by default. For the second button, "Next" is displayed if the page determined by nextPage exists, otherwise "OK", which closes the popup. "Previous" is active if the current page was reached via "Next". If a page was left on the way that defines a script for "onConfirm" but none for "onUndo", "Previous" is deactivated and none of the previous pages can be reached again. If the list contains only one page, it is displayed like a regular popup without "Previous" and "Next". Use cases, the exact flow and examples are described in the section Wizard and in detail for the PopupButton. Each of these objects can use the following parameters:

The parameters closeCaption and width always apply to the whole popup and cannot be defined per page.

Parameters for buttons

Wizard

Using the parameter pages, the popup becomes a wizard which guides the user step by step through a process (since Symcon 9.1). The pages of the PopupAlert behave exactly like those of the PopupButton. Use cases, the flow of Next, Previous and Cancel, the available variables, controlling page changes, notes and further examples are described for the PopupButton.

In contrast to the PopupButton, the PopupAlert is opened without a click of the user:

• If visible is true when the configuration form is loaded, the wizard is opened immediately. If GetConfigurationForm sets visible depending on the configuration, the wizard appears exactly when the instance still has to be set up.
• The module can open the wizard at any time via UpdateFormField using visible, e.g. via a button "Start setup", and close it with false. The wizard then starts on the page defined by initialPage or popup.initialPage. This also applies if the wizard is already open: If the module first sets popup.initialPage and then visible to true, the wizard switches to this page, e.g. via $this->UpdateFormField('SetupWizard', 'popup.initialPage', 'settings') and $this->UpdateFormField('SetupWizard', 'visible', true). The inputs are kept, "Previous" is deactivated afterwards.

Setup wizard

A proven pattern for setting up a module:

• The wizard is placed in actions and is made visible in GetConfigurationForm as long as a required property is not set.
• The first page welcomes the user and asks via a RadioButtonGroup how the setup should be done. The values of the options correspond to the names of the following pages, so nextPage can return the selection directly. One option allows skipping the setup.
• One page shows the result of a search. Its items are generated by the module via PHP code, so the search is executed again every time the page is shown.
• The onConfirm of the last settings page writes the values into the fields of the configuration form via UpdateFormField. The user sees the result and saves it with "Apply changes". The onUndo resets the fields to the saved values.
• Final pages are placed at the end of the list and are reached via their name: a summary and a note when the setup is skipped. The summary ends the wizard via "nextPage": -1 as the page for skipping still follows.
• A button in actions opens the wizard again.

Example: Setup wizard for a device in the network. As long as the property Host is empty, the wizard opens when the instance configuration is opened.

// Example: form.json
{
    "elements": [
        { "type": "ValidationTextBox", "name": "Host", "caption": "Host" },
        { "type": "NumberSpinner", "name": "Interval", "caption": "Update interval", "suffix": "seconds", "minimum": 10 }
    ],
    "actions": [
        {
            "type": "Button",
            "caption": "Start setup",
            "onClick": "SET_UIOpenWizard($id);"
        },
        {
            "type": "PopupAlert",
            "name": "SetupWizard",
            "visible": false,
            "popup": {
                "caption": "Setup",
                "width": "600px",
                "pages": [
                    {
                        "caption": "Welcome",
                        "items": [
                            { "type": "Label", "caption": "This wizard sets up the connection to the device." },
                            {
                                "type": "RadioButtonGroup",
                                "name": "WizardStart",
                                "caption": "How should the device be found?",
                                "value": "search",
                                "options": [
                                    { "caption": "Search in the network", "value": "search" },
                                    { "caption": "Enter address manually", "value": "manual" },
                                    { "caption": "Skip setup", "value": "skip" }
                                ]
                            }
                        ],
                        "nextPage": "return $WizardStart;"
                    },
                    {
                        "name": "search",
                        "caption": "Devices found",
                        "items": "return json_decode(SET_UIGetSearchItems($id), true);",
                        "validate": "if (($WizardFoundHost ?? '') == '') { return 'Please select a device'; }",
                        "nextPage": "settings"
                    },
                    {
                        "name": "manual",
                        "caption": "Address",
                        "items": [
                            { "type": "ValidationTextBox", "name": "WizardManualHost", "caption": "Host", "validate": "^[a-zA-Z0-9.:-]+$" }
                        ]
                    },
                    {
                        "name": "settings",
                        "caption": "Settings",
                        "items": [
                            { "type": "NumberSpinner", "name": "WizardInterval", "caption": "Update interval", "suffix": "seconds", "value": 60 }
                        ],
                        "validate": "if ($WizardInterval < 10) { return 'The interval must be at least 10 seconds'; }",
                        "onConfirm": "SET_UIApply($id, ($WizardStart == 'search') ? ($WizardFoundHost ?? '') : $WizardManualHost, $WizardInterval);",
                        "onUndo": "SET_UIRevert($id);",
                        "nextPage": "summary"
                    },
                    {
                        "name": "summary",
                        "caption": "Done",
                        "items": [
                            { "type": "Label", "caption": "The settings have been entered in the configuration form. Please save them with \"Apply changes\"." }
                        ],
                        "nextPage": -1
                    },
                    {
                        "name": "skip",
                        "caption": "Setup skipped",
                        "items": [
                            { "type": "Label", "caption": "Without a host, the instance does not work. The setup can be continued at any time via \"Start setup\"." }
                        ]
                    }
                ]
            }
        }
    ]
}

// Example: 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);
        // The wizard opens automatically as long as the instance is not set up
        $form['actions'][1]['visible'] = ($this->ReadPropertyString('Host') == '');
        return json_encode($form);
    }

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

    // items of the page "search": Executed every time the page is shown
    public function UIGetSearchItems(): string
    {
        // In a real module, the devices are searched here, e.g. via DNS-SD
        $devices = ['192.168.1.20' => 'Device in the living room', '192.168.1.21' => 'Device in the basement'];

        if (count($devices) == 0) {
            return json_encode([
                ['type' => 'Label', 'caption' => 'No device was found. Please go back and enter the address manually.']
            ]);
        }
        $options = [];
        foreach ($devices as $host => $name) {
            $options[] = ['caption' => $name . ' (' . $host . ')', 'value' => $host];
        }
        return json_encode([
            ['type' => 'Select', 'name' => 'WizardFoundHost', 'caption' => 'Device', 'options' => $options, 'value' => $options[0]['value']]
        ]);
    }

    // onConfirm of the page "settings": Enters the values in the configuration form
    public function UIApply(string $Host, int $Interval)
    {
        $this->UpdateFormField('Host', 'value', $Host);
        $this->UpdateFormField('Interval', 'value', $Interval);
    }

    // onUndo of the page "settings": Restores the saved values
    public function UIRevert()
    {
        $this->UpdateFormField('Host', 'value', $this->ReadPropertyString('Host'));
        $this->UpdateFormField('Interval', 'value', $this->ReadPropertyInteger('Interval'));
    }
}

Example

{
    "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": "A title that is never seen since every page overrides it",
        "closeCaption": "Close dialog",
        "items": [
            {
                "type": "Label",
                "caption": "This element is never seen since every page has its own items"
            }
        ],
        "pages": [
            {
                "caption": "Start",
                "items": [
                    {
                        "type": "Label",
                        "caption": "Next page: Selection"
                    }
                ],
                "nextPage": 2
            },
            {
                "caption": "Never visible",
                "items": [
                    {
                        "type": "Label",
                        "caption": "This page is never shown since the start page jumps directly to the page at index 2, the selection"
                    }
                ]
            },
            {
                "caption": "Selection",
                "items": [
                    {
                        "type": "Select",
                        "name": "NextPage",
                        "options": [
                            {"value": "page1", "caption": "Go to page 1"},
                            {"value": "page2", "caption": "Go to page 2"},
                            {"value": "close", "caption": "Done, close"}
                        ],
                        "caption": "Choose next page"
                    }
                ],
                "nextPage": "return $NextPage;"
            },
            {
                "name": "page1",
                "caption": "Page 1",
                "items": [
                    {
                        "type": "Label",
                        "caption": "This is page 1 with 'Undo'"
                    }
                ],
                "onUndo": "echo 'Undo page 1';",
                "onConfirm": "echo 'Confirm page 1';"
            },
            {
                "name": "page2",
                "caption": "Page 2",
                "items": [
                    {
                        "type": "Label",
                        "caption": "This is page 2, there is no 'Undo'. This is also the last page of the wizard."
                    }
                ],
                "onConfirm": "echo 'Confirm page 2';"
            }
        ]
    }
}