Was können wir verbessern?

Dokumentation

(Bearbeiten)

Aktionen

Benötigt: IP-Symcon >= 6.0

Beschreibung

Es ist möglich eigene Aktionen als Teil der Bibliothek zu definieren. Diese können nach der Installation der Bibliothek wie unter Aktionen beschrieben verwendet werden. Werden Aktionen abgespeichert oder konfiguriert resultiert dies in drei Werten: Dem Aktionsziel, der AktionsID und den Aktionsparametern. Das Aktionsziel stellt hierbei das Zielobjekt dar, beispielsweise im Falle eines Ereignisses das darunterliegende Objekt. Die AktionsID identifiziert eindeutig die ausgewählte Aktion. Die Parameter sind eine Menge an Werten, welche individuell zur Aktion gehören. Hierdurch kann ein Benutzer eine Aktion weiter parametrisieren und beispielsweise angeben auf welchen Wert eine Variable geschaltet werden soll.

Struktur

Für jede Aktion, welche Teil der Bibliothek sein soll, muss eine JSON-Datei im Unterordner "actions" der Bibliothek erstellt werden. Diese JSON-Datei muss ein JSON-Objekt beinhalten, welches der folgenden Struktur folgt.

Parameter Datentyp Beschreibung
id string Einmalige GUID zur eindeutigen Identifikation der Aktion. GUID Generator
caption string Sichtbare Bezeichnung der Aktion
form array/string Dieses Feld kann ein Array von Konfigurationselementen beinhalten wie in den Bereichen "elements" oder "actions" der Konfigurationsformulare. Alternativ kann das Formular durch ein PHP-Skript dynamisch generiert werden. In diesem Fall enthält dieses Feld den entsprechenden Code, welcher das Konfigurationsformular als Objekt zurückgibt. Der PHP-Code kann auf mehrere Strings in einem Array aus Strings aufgeteilt werden. Soll eine bereits definierte Aktion bearbeitet werden, beispielsweise in einem Ereignis, so stehen die definierten Parameter als Systemvariablen zur Verfügung, siehe SelectAction. Die Einstellungen des Formulars stellen die Parameter der Aktion dar, wobei jedes benannte Konfigurationselement seinen Wert unter seinem "name" zur Verfügung stellt.
action array/string PHP-Code, welcher die Ausführung der Aktion definiert. Wird die Aktion ausgeführt, so wird der PHP-Code aus diesem Feld ausgeführt. Dabei stehen die Parameter als Systemvariablen zur Verfügung.
priority int Priorität der Aktion, in einer Auswahl werden Aktionen nach der Priorität sortiert
category (optional) string (default: "other") Die Kurzform der Kategorie der Aktion. Mögliche Kategorien sind unter category aufgelistet.
restrictions (optional) array (default: []) Eine Liste von Restriktionen, welche einschränken, unter welchen Bedingungen diese Aktion angeboten wird. Die möglichen Restriktionen sind in den Tabellen restrictions beschrieben.
locale (optional) object (default: []) Hier kann wie in der Lokalisierung eines Moduls die Aktion lokalisiert werden. Hierdurch wird sowohl die Form als auch die caption lokalisiert.
format (optional) string (default: Inhalt von caption) Dieser String stellt eine Kurzformatierung der Aktion mit ihren Parametern dar, welche an verschiedenen Stellen angezeigt werden kann. Die Formatierung wird in ICU-Syntax notiert. Dort können als Variablen die Parameter (Name entsprechend des Parameters) sowie des Ziel (Name "TARGET") verwendet werden. Für die Formatierung stehen einige zusätzliche Symcon-spezifische Typen zur Verfügung. Der Inhalt von format wird durch die locale übersetzt.
description (optional) string (default: "") Dieser Text wird als Beschreibung für die Aktion in der Aktionsauswahl angezeigt. Der Inhalt von description wird durch die locale übersetzt.
readable (optional) array/string (default: Inhalt von action, wobei alle Statusvariablen von Parametern durch die eingestellten Werte ersetzt werden) PHP-Code, welcher die Aktion als lesbaren Code zurückgibt. Dies wird beispielsweise für "Befehle einfügen" im Skripteditor verwendet. Dabei stehen die Parameter als Systemvariablen zur Verfügung.

category

Kurzform Name Beschreibung
target Zielspezifisch Aktionen, die zu einem spezifischen Ziel gehören, üblicherweise einem Modul
math Mathematische Operationen Mathematische Operationen um Objekte zu modifizieren
set Wert setzen Aktionen, die den Wert einer Variable setzen
switch Wert schalten Aktionen, die den Wert einer Variable schalten
expert Experte Aktionen, die tieferes Verständniss über IP-Symcon oder PHP erfordern
other Andere Aktionen Aktionen, die in keine andere Kategorie passen

restrictions

Restriktionen für alle Objekttypen
Parameter Datentyp Beschreibung
objectType array Die Aktion wird nur für Ziele der angegebenen Typen angeboten (0 = Kategorie, 1 = Instanz, 2 = Variable, 3 = Skript, 4 = Ereignis, 5 = Media, 6 = Link)
includeEnvironments array Eine Liste von Umgebungen in welchen die Aktion angeboten wird, siehe Umgebungen
excludeEnvironments array Eine Liste von Umgebungen in welchen die Aktion nicht angeboten wird. Bei Übereinstimmungen mit "includeEnvironments" wird die Aktion nicht angezeigt. Siehe Umgebungen
writable bool Ist diese Restriktion auf true gesetzt, so wird die Aktion nur angeboten, falls das Zielobjekt nicht schreibgeschützt sein. Ist das Ziel eine Variable, so darf diese zusätzlich keine Variablenaktion haben.
Restriktionen für Zielobjekte vom Typ Instanz
Parameter Datentyp Beschreibung
hasActionStatusVariables bool Ist diese Restriktion auf true gesetzt, so wird die Aktion nur angeboten, falls die Instanz mindestens eine schaltbare Statusvariable hat
hasInstanceFunctions bool Ist diese Restriktion auf true gesetzt, so wird die Aktion nur angeboten, falls die Instanz mindestens eine öffentliche Funktion besitzt, welche nicht vom IPSModule geerbt wurde
moduleID array Die Aktion wird nur angeboten, falls die ModulID der Zielinstanz in dieser Liste enthalten ist
Restriktionen für Zielobjekte vom Typ Variable
Parameter Datentyp Beschreibung
requestAction bool Ist diese Restriktion auf true gesetzt, so wird die Aktion nur angeboten, falls die Variable über eine Variablenaktion verfügt
variableType array Die Aktion wird nur angeboten, falls der Variablentyp der Zielvariablen in dieser Liste enthalten ist (0 = Boolean, 1 = Integer, 2 = Float, 3 = String)
profilesInclude array Die Aktion wird nur angeboten, falls der Name ihres aktuell verwendetes Profils in dieser Liste enthalten ist
profilesExclude array Die Aktion wird nur angeboten, falls der Name ihres aktuell verwendeten Profils NICHT in dieser Liste enthalten ist
profileIsEnum bool Ist diese Restriktion auf true gesetzt, so wird die Aktion nur angeboten, falls das Profil der Variablen eine Aufzählung darstellt (Schrittweite = 0, mindestens eine Assoziation)
profileIsPercentage bool Ist diese Restriktion auf true gesetzt, so wird die Aktion nur angeboten, falls das Profil der Variablen einen Prozentwert darstellt (Suffix = "%", Max Wert > Min Wert)
Umgebungen
Umgebung Beschreibung
Default Die Standardumgebung in welcher die meisten Aktionen definiert sind, viele Auswahlen beschränken sich auf diese Aktionen oder bieten sie zusätzlich an
TestCommands Aktionsauswahl im "Befehle testen"-Dialog einer Instanz, hier werden "Default"-Aktionen nicht mit angeboten
EventTrigger Aktionsauswahl in einem ausgelösten Ereignis
EventCyclic Aktionsauswahl in einem zyklischen Ereignis
EventSchedule Aktionsauswahl in einem Wochenplan
FlowScript Aktionsauswahl im Ablaufplan
ScriptEditor Aktionsauswahl im "Befehl hinzufügen"-Dialog eines Skripteditors
Weitere Umgebungen Es können eigene Umgebungen definiert werden, um beispielsweise spezielle Aktionen als Teil einer Instanzkonfiguration anzubieten

Systemvariablen

Sowohl in einem möglichen PHP-Skript für die Form als auch in dem Skript für die Ausführung kann via Systemvariablen auf das Ziel der Aktion und die eingestellten Parameter zugegriffen werden. So stehen folgende Systemvariablen in diesen Skripten zur Verfügung:

Systemvariable Beschreibung
$_IPS['TARGET'] ObjektID des Ziels der Aktion
$_IPS[(Name des Parameters)] (z.B. $_IPS['VALUE']) Der eingestellte bzw. ausgewählte Wert des Parameters. Diese Felder stehen in einem Skript für die Form nicht zur Verfügung, falls die Aktion initial ausgewählt wird und somit noch keine Parameter ausgewählt wurden. Daher sollte dort mit der PHP-Funktion isset geprüft werden, ob die Systemvariablen vorhanden sind.
Weitere Systemvariablen Weitere Systemvariablen stehen basierend auf der Ausführung der Aktion zur Verfügung. Sollte es hierbei zu Überschneidungen mit Parameternamen kommen, werden die Parameterwerte verwendet und es kann nicht auf die regulären Systemvariablen zugegriffen werden.

Formatierung

Im Feld format können alle Typen des ICU-Formats verwendet werden. Zusätzlich wurden Symcon-spezifische Typen eingeführt. Wie bei ICU üblich, bestehen diese aus drei Teilen: Der Parameterbezeichnung, der Typbezeichnung und optionalen zusätzlichen Parametern.

profile

Der Wert wird auf Basis des Profils der Zielvariablen dargestellt. Hat das Ziel kein Profil, so wird der Wert direkt dargestellt.

Beispiele: {VALUE, profile}

object

Es wird der Name des Objekts mit der ObjektID des Wertes dargestellt.

Parameter Beschreibung
ident (optional) Wird als Parameter "ident" gefolgt von einer Parameterbezeichnung angegeben, so wird stattdessen der Name des Kindes mit dem Ident, welcher dem Parameter entspricht, dargestellt. Steht der Wert hinter ident in einfachen Anführungszeichen ('), so wird der Wert dazwischen direkt als Ident verwendet.

Beispiele: {VARIABLE, object}, {TARGET, object, ident IDENT}

action

Es wird die Formatierung der Aktion, welche als JSON-String codiert im Wert steht, dargestellt.

Parameter Beschreibung
targetID (optional) Wird als Parameter "targetID" gefolgt von einer Parameterbezeichnung angegeben, so wird die ZielID der formatierten Aktion auf den Wert des entsprechenden Parameters gesetzt. Wird zusätzlich direkt danach "ident" gefolgt von einer Parameterbezeichnung angegeben, so wird die ZielID stattdessen auf die ObjektID des Kindes mit dem Ident, welcher dem Parameter entspricht, dargestellt. Steht der Wert hinter ident in einfachen Anführungszeichen ('), so wird der Wert dazwischen direkt als Ident verwendet.

Beispiele: {ACTION, action}, {ACTION, action, targetID VARIABLE}, {ACTION, action, targetID TARGET ident IDENT}

scheduleAction

Es werden die Namen von Wochenplanaktionen von Wochenplänen unter dem angegebenen Elternobjekt mit der ID des Wertes dargestellt.

Parameter Beschreibung
parent Wird als Parameter "parent" gefolgt von einer Parameterbezeichnung angegeben, so wird als Elternobjekt des Objekt mit dem Wert als ID verwendet
action Wird als Parameter "action" gefolgt von einer AktionsID in einfachen Anführungszeichen (') angegeben, so werden nur Namen von Wochenplanaktionen dargestellt, welche die entsprechende Aktion ausführen

Beispiele: {SCHEDULE_ACTION, scheduleAction, parent PARENT}, {SCHEDULE_ACTION, scheduleAction, parent PARENT action '{7938A5A2-0981-5FE0-BE6C-8AA610D654EB}'}

Beispiele

switchValueString.json

{
    "id": "{A4D52B67-BE4B-4AD0-964F-B9BA2556AAB0}",
    "caption": "Switch to Value",
    "form": [
        {
            "type": "ValidationTextBox",
            "name": "VALUE",
            "caption": "Value"
        }
    ],
    "action": "RequestAction($_IPS['TARGET'], $_IPS['VALUE']);",
    "restrictions": {
        "objectType": [ 2 ],
        "variableType": [ 3 ],
        "profileIsEnum": false,
        "requestAction": true
    },
    "priority": 10,
    "locale": {
        "de": {
            "Switch to Value": "Schalte auf Wert",
            "Value": "Wert",
            "Set to {VALUE, profile}": "Setze auf {VALUE, profile}"
        }
    },
    "format": "Set to {VALUE, profile}"
}

setValueIntegerPreviousReminder.json

{
    "id": "{92971E6F-4AC1-BEF8-B325-9E044D27B3EB}",
    "caption": "Set to Value",
    "form": [
        "$form = [",
        "    {",
        "        'type' => 'SelectColor',",
        "        'name' => 'VALUE',",
        "        'allowTransparent' => false,",
        "        'caption' => 'Value',",
        "        'writable' => true",
        "    }",
        "];",
        "if (isset($_IPS['VALUE'])) {",
        "    $form[] = {",
        "        'type' => 'Label'",
        "        'caption' => 'Previously selected value: ' . $_IPS['VALUE']",
        "    };",
        "}",
        "return $form;"
    ],
    "action": "SetValue($_IPS['TARGET'], $_IPS['VALUE']);",
    "restrictions": {
        "objectType": [ 2 ],
        "variableType": [ 1 ],
        "profilesExclude": [ "~HexColor" ]
    },
    "priority": 5,
    "locale": {
        "de": {
            "Set to Value": "Setze auf Wert",
            "Value": "Wert",
            "Set to {VALUE, profile}": "Setze auf {VALUE, profile}"
        }
    },
    "format": "Set to {VALUE, profile}"
}

switchStatusVariable.json

{
    "id": "{E616C2B2-A827-1712-4AE0-841C57B3DD74}",
    "caption": "Switch Status Variable",
    "form": [
        "$options = [];",
        "$firstVariable = false;",
        "foreach (IPS_GetChildrenIDs($_IPS['TARGET']) as $childID) {",
        "    $object = IPS_GetObject($childID);",
        "    if (($object['ObjectType'] === 2) && ($object['ObjectIdent'] !== '')) {",
        "        if (!HasAction($childID)) {",
        "            continue;",
        "        }",
        "        if (!$firstVariable) {",
        "            $firstVariable = $object;",
        "        }",
        "        $options[] = [",
        "            'caption' => $object['ObjectName'],",
        "            'value' => $object['ObjectIdent']",
        "        ];",
        "    }",
        "}",
        "return [",
        "   [",
        "       'type' => 'Select',",
        "       'name' => 'IDENT',",
        "       'caption' => 'Status Variable',",
        "       'options' => $options,",
        "       'value' => $firstVariable['ObjectIdent'],",
        "       'onChange' => 'IPS_UpdateFormField(\"ACTION\", \"targetID\", IPS_GetObjectIDByIdent($IDENT, ' . $_IPS['TARGET'] . '), $id);'",
        "   ],",
        "   [",
        "       'type' => 'SelectAction',",
        "       'name' => 'ACTION',",
        "       'caption' => 'Action',",
        "       'targetID' => isset($_IPS['IDENT']) ? IPS_GetObjectIDByIdent($_IPS['IDENT'], $_IPS['TARGET']) : $firstVariable['ObjectID']",
        "   ]",
        "];"
    ],
    "action": [
        "$targetVariableID = IPS_GetObjectIDByIdent($_IPS['IDENT'], $_IPS['TARGET']);",
        "$action = json_decode($_IPS['ACTION'], true);",
        "echo IPS_RunActionWait($action['actionID'], $targetVariableID, $action['parameters']);"
    ],
    "restrictions": {
        "objectType": [ 1 ],
        "hasActionStatusVariables": true
    },
    "locale": {
        "de": {
            "Switch Status Variable": "Schalte Statusvariable",
            "Status Variable": "Statusvariable",
            "{TARGET, object, ident IDENT}: Switch Variable": "{TARGET, object, ident IDENT}: Schalte Variable"
        }
    },
    "format": "{TARGET, object, ident IDENT}: {ACTION, action, targetID TARGET ident IDENT}",
    "readable": [
        "$targetVariableID = IPS_GetObjectIDByIdent($_IPS['IDENT'], $_IPS['TARGET']);",
        "$action = json_decode($_IPS['ACTION'], true);",
        "$action['parameters']['TARGET'] = $targetVariableID;",
        "$action['parameters']['ENVIRONMENT'] = $_IPS['ENVIRONMENT'];",
        "$action['parameters']['PARENT'] = $_IPS['PARENT'];",
        "echo IPS_GetActionReadableCode($action['actionID'], $action['parameters']) . \"\\n\";"
    ]
}
Zum Warenkorb
Haben Sie noch Fragen?