« Back to Product

Documentation

Send feedback!

IPS_GetActionForm

 string IPS_GetActionForm (string $ActionID, array $Parameters)

Parameters

ActionID

GUID of the action
Parameters

Parameters of the action, at least TARGET, PARENT and ENVIRONMENT

Returns

A JSON encoded string with the array of form elements.

Description

The function generates the configuration form of the action with the GUID ActionID. The form of an action (entry form, see IPS_GetActions) is either static, i.e. an array of form elements, or dynamic as PHP code. Only dynamic forms can be generated with this function. The PHP code is run with the Parameters as system variables (e.g. $_IPS['TARGET']), and the returned array is returned JSON encoded. This way, the form can depend on the target object or on parameters that were already selected. The function waits until the execution has finished.

The Parameters need to include the following entries:

Parameter Description
TARGET ID of the target object of the action (-1 for general actions)
PARENT ID of the object that executes the action, e.g. the PHP script or the flow script
ENVIRONMENT The environment of the action, see Environments

Further entries, e.g. parameters that were already selected, are available to the PHP code as well. Only Boolean, Integer, Float and String are possible as values.

The checks are done in this order:

  • If ActionID is not a valid GUID, the function fails with "ActionID ... is not a valid GUID".
  • If the action does not exist, it fails with "Action with ID ... not found!".
  • If a required parameter is missing, it fails with "TARGET is missing in Parameters", "PARENT is missing in Parameters" or "ENVIRONMENT is missing in Parameters".
  • For a static form, it fails with "GetActionForm should only be called for dynamic forms (string, array of strings)!".

The captions in the form are not translated, the translations are in the entry locale of the action.

Example

$form = IPS_GetActionForm('{46B65CA6-3098-4982-9A6C-B89DADBB0A96}', [
    'TARGET'      => 12345, // Boolean variable
    'PARENT'      => $_IPS['SELF'],
    'ENVIRONMENT' => 'Default'
]);
print_r(json_decode($form, true));

/* e.g. returns:
Array
(
    [0] => Array
        (
            [type] => Select
            [name] => VALUE
            [caption] => Value
            [options] => Array
                (
                    [0] => Array
                        (
                            [value] =>
                            [caption] => Off
                        )

                    [1] => Array
                        (
                            [value] => 1
                            [caption] => On
                        )

                )

        )

)
*/
Any questions?