Using a wizard for additional parameters¶

You may need to ask user for more than a single parameter. And as a single string is used to store and pass them to your method, you will have to encode them in some way, either as a comma-separated list of values or as a JSON string or even as XML. This means you hardly can expect user to remember the exact syntax to be used to specify all those parameters.

You already know of many extensions providing a wizard to help you prepare plugin configuration. With this extension, you also have the opportunity to create a wizard. The wizard is typically written in JavaScript and basically supports whatever you may do with a TCA wizard of type “userFunc”.

Screenshot below shows an additional icon next to the parameter field:

In order to display the parameter wizard icon (), you have to write a method getWizard() in your class that returns either the JavaScript code to be executed when user clicks on the icon or a full HTML snippet to be included after the field:

public function getWizard(string $methodName, array &$PA, bool $checkOnly = false) : ?string
{
        $js = null;

        if ($methodName === 'myRecipientList') {
                if ($checkOnly) {
                        // We just need to return some non-empty string to show the wizard button
                        return 'ok';
                }

                $js = '
                        var params = document.'.$PA['formName'].'[\''.$PA['itemName'].'\'].value;
                        if (params == "") params = 2;
                ';

                // Show a standard javascript prompt and assign result to the parameters field
                // This information will be saved with form and available in myRecipientList
                $js .= '
                        var r = prompt("How many items do you want in your list?", params);
                        if (r != null) {
                                document.'.$PA['formName'].'[\''.$PA['itemName'].'\'].value =
                                        parseInt(r);'.
                                implode('', $PA['fieldChangeFunc']) .';
                        }
                ';
        }

        return $js;
}

Parameters of the getWizard method are:

• $methodName : Name of the method for which a wizard may be specified.
• $PA : The full TCA configuration for the parameter field. Passed by reference. This allows you to change the way the input field itself is rendered.
• $checkOnly : If true, you should only return an non-empty string if some JS is needed. This is used by the FormEngine to show the wizard button next to the parameter field. The actual JS should be returned if $checkOnly is false.

If you run code written in method getWizard() above, you will get a standard JavaScript prompt that asks you the number of recipients you want to get in your recipient list: