Wizards Configuration

Wizards are configurable for some field types, namely “input”, “text”, “select” and “group” types. They provide a way to insert helper- elements, links to wizard scripts etc.

A well known example of a wizard application is the form wizard (as provided by the “form” system extension):

The forms wizard's icon

Click on the forms icon wizard to display the forms editor

The wizard is configured for the text area field and appears as an icon to the right. Clicking the icon will guide the user to a view where the “cryptic” form code is presented in a more user-friendly interface:

The forms visual editor

The visual forms editor provided by the “form” system extension

Another example of wizards are the new / edit / suggest wizards which are available for “group” or “select” type fields:

Several wizards associated with a field

New, edit and suggest wizard, associated with a form field

Configuration of wizards

The value of the “wizards” key in the field config-array is an array. Each key is yet another array which configures the individual wizards for a field. The order of the keys determines the order the wizards are displayed in. The key-values themselves play no important role (except from a few reserved words listed in a table below).

Warning

Configuration of wizards has changed since TYPO3 CMS 6.2 to provide CSRF protection. To see examples for older version of TYPO3 CMS please refer to other versions of this manual.

The configuration for the new / edit / suggest wizards shown above looks like this:

'basedOn' => array(
        'label' => 'LLL:EXT:cms/locallang_tca.xlf:sys_template.basedOn',
        'config' => array(
                ...
                'wizards' => array(
                        '_VERTICAL' => 1,
                        'suggest' => array(
                                'type' => 'suggest'
                        ),
                        'edit' => array(
                                'type' => 'popup',
                                'title' => 'Edit template',
                                'module' => array(
                                        'name' => 'wizard_edit',
                                ),
                                'popup_onlyOpenIfSelected' => 1,
                                'icon' => 'EXT:backend/Resources/Public/Images/FormFieldWizard/wizard_edit.gif',
                                'JSopenParams' => 'height=350,width=580,status=0,menubar=0,scrollbars=1'
                        ),
                        'add' => array(
                                'type' => 'script',
                                'title' => 'LLL:EXT:cms/locallang_tca.xlf:sys_template.basedOn_add',
                                'icon' => 'EXT:backend/Resources/Public/Images/FormFieldWizard/wizard_add.gif',
                                'params' => array(
                                        'table' => 'sys_template',
                                        'pid' => '###CURRENT_PID###',
                                        'setValue' => 'prepend'
                                ),
                                'module' => array(
                                        'name' => 'wizard_add'
                                )
                        )
                )
        )
),

The first two lines of the “wizards” configuration make use of two reserved keywords to define settings for the display of icons.

Reserved keys

Each wizard is identified by a key string. However some strings are reserved for general configuration. These are listed in this table and as a rule of thumb they are prefixed with an underscore (“_”):

_POSITION

Key

_POSITION

Type

string

Description

Determines the position of the wizard icons/titles.

Default is “right”.

Possible values are “left”, “top”, “bottom”.

_ VERTICAL

Key

_VERTICAL

Type

boolean

Description

If set, the wizard icons (if more than one) will be positioned in a column (vertically) and not a row (horizontally, which is default)

[any other key]

Key

[any other key]

Type

PHP array

Description

Configuration of the wizard types, see below.

General configuration options

This table lists the general configuration options for (almost) all wizard types. In particular the value of the “type” key is important because it denotes what additional options are available.

type

Key

type

Type

string

Description

Defines the type of wizard. The options are listed as headlines in the table below.

This setting is required!

title

Key

title

Type

string or LLL reference

Description

This is the title of the wizard. For those wizards which require a physical representation – e.g. a link - this will be the link if no icon is presented.

icon

Key

icon

Type

fileref

Description

This is the icon representing the wizard.

If the first 3 chars are not “../” then the file is expected to be in typo3/sysext/t3skin/icons/gfx/. To insert custom images, put them into an extension and use an icon path like EXT:ext/[extension key]/directory/.... Generally, the format is the same as for referring to icons for selector box options.

If the icon is not set, the title will be used for the link.

enableByTypeConfig

Key

enableByTypeConfig

Type

boolean

Description

If set, then the wizard is enabled only if declared in the Special Configuration of specific types (using wizards[list of wizard-keys]).

RTEonly

Key

RTEonly

Type

boolean

Description

If set, then this wizard will appear only if the wizard is presented for a RTE field.

Specific wizard configuration options based on type

Script wizard

type

Key

type

Type

string

Description

[Must be set to “script”]

Creates a link to an external script which can do “context sensitive” processing of the field. This is how the Form and Table wizards are used.

notNewRecords

Key

notNewRecords

Type

boolean

Description

If set, the link will appear only if the record is not new (that is, it has a proper UID)

module

Key

module

Type

array

Description

(Since TYPO3 CMS 6.2)

This array contains configuration matching a declared wizard. For example, the “Add record” wizard is declared that way in typo3/sysext/backend/ext_tables.php:

// Register add wizard
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addModulePath(
        'wizard_add',
        \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::extPath($_EXTKEY) . 'Modules/Wizards/AddWizard/'
);

Note the key named wizard_add. This key is used when configuring a wizard, as in:

'module' => array(
        'name' => 'wizard_add'
)

params

Key

params

Type

array

Description

Here you can put values which are passed to your script in the P array.

User-defined wizards

type

Key

type

Type

string

Description

[Must be set to “userFunc”]

Calls a user function/method to produce the wizard or whatever they are up to.

notNewRecords

Key

notNewRecords

Type

boolean

userFunc

Key

userFunc

Type

string

Description

Calls a function or a method in a class.

Methods: [classname]->[methodname]

Functions: [functionname]

The function/class must be included on beforehand. This is advised to be done within the localconf.php file.

Two parameters are passed to the function/method:

  1. an array with parameters, much like the ones passed to scripts. One key is special though: the “item” key, which is passed by reference. So if you alter that value it is reflected back!
  2. a back-reference to the calling TCEform-object.

The content returned from the function call is inserted at the position where the the icon/title would normally go.

See full example below.

Colorbox wizards

type

Key

type

Type

string

Description

[Must be set to “colorbox”]

Renders a square box (table) with the background color set to the value of the field. The id-attribute is set to a md5-hash so you might change the color dynamically from pop-up- wizard.

The icon is not used, but the title is given as alt-text inside the color-square.

exampleImg

Key

exampleImg

Type

string

Description

Reference to a sample (relative to PATH_typo3 directory).

You can prefix with EXT: to get image from extension.

An image 350 pixels wide is optimal for display.

Example

'exampleImg' => 'gfx/wizard_colorpickerex.jpg'

Select wizards

type

Key

type

Type

string

Description

[Must be set to “select”]

This renders a selector box. When a value is selected in the box, the value is transferred to the field and the field (default) element is thereafter selected (this is a blank value and the label is the wizard title).

“select” wizards make no use of the icon.

The “select” wizard’s select-properties can be manipulated with the same number of TSconfig options which are available for “real” select-type fields in TCEFORM.[table].[field]. The position of these properties is TCEFORM.[table].[field].wizards.[wizard-key].

mode

Key

mode

Type

append, prepend, [blank]

Description

Defines how the value is processed: either added to the front or back or (default) substitutes the existing.

items

Key

items

foreign_table_

etc…

Type

Options related to the selection of elements as known from select-type fields.

Description

Example

'items' => array(
        array('8 px', '8'),
        array('10 px', '10'),
        array('11 px', '11'),
        array('12 px', '12'),
        array('14 px', '14'),
        array('16 px', '16'),
        array('18 px', '18'),
        array('20 px', '20')
)

Suggest wizards

type

Key

type

Type

string

Description

[Must be set to “suggest”]

This renders an input field next to the selector of group-type fields (when internal_type is db) or of select-type fields (using foreign_table). After the user has typed at least 2 (minimumCharacters) characters in this field, a search will start and show a list of records matching the search word. The “suggest” wizard’s properties can be configured directly in TCA or in page TSconfig (see TCEFORM properties).

Important

The configuration options are applied to each table queried by the suggest wizard. There’s a general default configuration that applies to all tables. On top of that, there can be specific configurations for each table (use the table name as a key).

See wizard example below.

pidList

Key

pidList

Type

list of values

Description

Limit the search to certain pages (and their subpages). When pidList is empty all pages will be included in the search (as long as the be_user is allowed to see them).

Example

$TCA['pages']['columns']['storage_pid']['config']['wizards']['suggest'] = array(
        'type' => 'suggest',
        'default' => array(
                'pidList' => '1,2,3,45',
        ),
);

pidDepth

Key

pidDepth

Type

integer

Description

Expand pidList by this number of levels. Has an effect only if pidList has a value.

Example

$TCA['pages']['columns']['storage_pid']['config']['wizards']['suggest'] = array(
        'type' => 'suggest',
        'default' => array(
                'pidList' => '6,7',
                'pidDepth' => 4
        ),
);

minimumCharacters

Key

minimumCharacters

Type

integer

Description

Minimum number of characters needed to start the search. Works only in “default” configuration.

maxItemsInResultList

Key

maxItemsInResultList

Type

integer

Description

Maximum number of results to display, default is 10.

maxPathTitleLength

Key

maxPathTitleLength

Type

integer

Description

Maximum number of characters to display when a path element is too long.

searchWholePhrase

Key

searchWholePhrase

Type

boolean

Description

Whether to do a LIKE=%mystring% (searchWholePhrase = 1) or a LIKE=mystring% (to do a real find as you type), default is 0.

Example

$TCA['pages']['columns']['storage_pid']['config']['wizards']['suggest'] = array(
        'type' => 'suggest',
        'default' => array(
                'searchWholePhrase' => 1,
        ),
);

searchCondition

Key

searchCondition

Type

string

Description

Additional WHERE clause (not prepended with AND).

Example

// configures the suggest wizard for the field "storage_pid" in table "pages" to search only for pages with doktype=1
$TCA['pages']['columns']['storage_pid']['config']['wizards']['suggest'] = array(
        'type' => 'suggest',
        'default' => array(
                'searchCondition' => 'doktype=1',
        ),
);

additionalSearchFields

Key

additionalSearchFields

Type

string

Description

(Available since TYPO3 CMS 6.0)

Comma-separated list of fields the suggest wizard should also search in. By default the wizard looks only in the fields listed in the “label” and “label_alt” properties.

cssClass

Key

cssClass

Type

string

Description

Add a CSS class to every list item of the result list.

receiverClass

Key

receiverClass

Type

string

Description

PHP class alternative receiver class. Must extend TYPO3\\CMS\\Backend\\Form\\Element\\SuggestDefaultReceiver.

renderFunc

Key

renderFunc

Type

string

Description

User function to manipulate the displayed records in the results.

Slider wizards

type

Key

type

Type

string

Description

[Must be set to “slider”]

This renders a slider next to the field. It works for either input- type fields or select-type fields. For select-type fields, the wizard will “slide” through the items making up the field. For input-type fields, it will work only for fields evaluated to integer, float and time. It is advised to also define a “range” property, otherwise the slider will go from 0 to 10000.

step

Key

step

Type

integer/float

Description

Sets the step size the slider will use. For floating point values this can itself be a floating point value.

width

Key

width

Type

pixels

Description

Defines the width of the slider

Examples

In the next section the more complex core wizard scripts are demonstrated with examples.

Selector box of preset values

You can add a selector box containing preset values next to a field:

Select wizard

The select wizard with its list of options

When an option from the selector box is selected it will be transferred to the input field of the element. The mode of transfer can be either substitution (default) or prepending or appending the value to the existing value.

This is the corresponding TCA configuration:

'season' => array(
        'exclude' => 0,
        'label' => 'LLL:EXT:examples/Resources/Private/Language/locallang_db.xlf:tx_examples_haiku.season',
        'config' => array(
                'type' => 'input',
                'size' => 20,
                'eval' => 'trim',
                'wizards' => array(
                        'season_picker' => array(
                                'type' => 'select',
                                'mode' => '',
                                'items' => array(
                                        array('LLL:EXT:examples/Resources/Private/Language/locallang_db.xlf:tx_examples_haiku.season.spring', 'Spring'),
                                        array('LLL:EXT:examples/Resources/Private/Language/locallang_db.xlf:tx_examples_haiku.season.summer', 'Summer'),
                                        array('LLL:EXT:examples/Resources/Private/Language/locallang_db.xlf:tx_examples_haiku.season.autumn', 'Autumn'),
                                        array('LLL:EXT:examples/Resources/Private/Language/locallang_db.xlf:tx_examples_haiku.season.winter', 'Winter'),
                                )
                        )
                )
        )
),

User defined wizard (processing with PHP function)

The “userFunc” type of wizard allows you to render all the wizard code yourself. Theoretically, you could produce all of the other wizard kinds (“script”, “popup”, “colorbox”, etc.) with your own user function if you wanted to alter their behavior.

In this example the wizard provides to JavaScript-powered buttons that make it possible to increase or decrease the value in the field by 1. The wizard also highlights the field with a background color. This is how it looks:

User-defined wizard

The input field with its custom wizard

The corresponding configuration is:

'weirdness' => array(
        'exclude' => 0,
        'label' => 'LLL:EXT:examples/Resources/Private/Language/locallang_db.xlf:tx_examples_haiku.weirdness',
        'config' => array(
                'type' => 'input',
                'size' => 10,
                'eval' => 'int',
                'wizards' => array(
                        'specialWizard' => array(
                                'type' => 'userFunc',
                                'userFunc' => 'Documentation\\Examples\\Userfuncs\\Tca->someWizard',
                                'params' => array(
                                        'color' => 'green'
                                )
                        )
                )
        )
),

Notice the params array, which is passed to the user function that handles the wizard. And here’s the code of the user function (from file EXT:examples/Classes/Userfuncs/Tca.php):

public function someWizard($PA, $fObj) {
        // Note that the information is passed by reference,
        // so it's possible to manipulate the field directly
        // Here we highlight the field with the color passed as parameter
        $backgroundColor = 'white';
        if (!empty($PA['params']['color'])) {
                $backgroundColor = $PA['params']['color'];
        }
        $PA['item'] = '<div style="background-color: ' . $backgroundColor . '; padding: 4px;">' . $PA['item'] . '</div>';

        // Assemble the wizard itself
        $output = '<div style="margin-top: 8px; margin-left: 4px;">';

        $commonJavascriptCalls = $PA['fieldChangeFunc']['TBE_EDITOR_fieldChanged'] . $PA['fieldChangeFunc']['typo3form.fieldGet'] . ' return false;';
        // Create the + button
        $onClick = "document." . $PA['formName'] . "['" . $PA['itemName'] . "'].value++; " . $commonJavascriptCalls;
        $output .= '<a href="#" onclick="' . htmlspecialchars($onClick) . '" style="padding: 6px; border: 1px solid black; background-color: #999">+</a>';
        // Create the - button
        $onClick = "document." . $PA['formName'] . "['" . $PA['itemName'] . "'].value--; " . $commonJavascriptCalls;
        $output .= '<a href="#" onclick="' . htmlspecialchars($onClick) . '" style="padding: 6px; border: 1px solid black; background-color: #999">-</a>';
        $output .= '</div>';
        return $output;
}

First the HTML code of the field itself is manipulated, by adding a div tag around it. Notice how all you need to do is to change the value of $PA['item'] since that value is passed by reference to the function and therefore doesn’t need a return value - only to be changed. In that div, we use the color received as parameter.

After that we create the JavaScript and the links for both the “+” and “-” buttons and we return the resulting HTML code. Note that the $PA contains important JavaScript code to use. This code marks the field on which the wizard acted as changed and updates the value in the corresponding hidden field.

Use the debug() function to find more about what is available in the $PA array.

Add a suggest wizard

As an example, let’s look at the suggest wizard setup for the “related_record” field of the “haiku” table. The wizard looks like this:

The suggest wizard

The suggest wizard next to the record selector

And here’s the wizard in action:

The suggest wizard in action

The suggest wizard shows suggestions

This is the corresponding TCA configuration:

'related_records' => array(
        'label' => 'LLL:EXT:examples/Resources/Private/Language/locallang_db.xlf:tx_examples_haiku.related_records',
        'config' => array(
                'type' => 'group',
                'internal_type' => 'db',
                'allowed' => 'pages, tt_content',
                ...
                'wizards' => array(
                        'suggest' => array(
                                'type' => 'suggest',
                                'default' => array(
                                        'searchWholePhrase' => 1
                                ),
                                'pages' => array(
                                        'searchCondition' => 'doktype = 1'
                                )
                        )
                )
        )
)

The tables that are queried are the ones used in the allowed property, i.e. the “pages” and “tt_content” tables.

The wizard can be configured differently for each of these tables. The settings in “default” is applied to all tables. In the example above, there’s a special setting for the “pages” table to search only standard pages.

Add a slider wizard

The “haiku” table in the “examples” extension implements a slider wizard for the “Angle” field. The field configuration looks like this:

'angle' => array(
        'exclude' => 0,
        'label' => 'LLL:EXT:examples/Resources/Private/Language/locallang_db.xlf:tx_examples_haiku.angle',
        'config' => array(
                'type' => 'input',
                'size' => 5,
                'eval' => 'trim,int',
                'range' => array(
                        'lower' => -90,
                        'upper' => 90
                ),
                'default' => 0,
                'wizards' => array(
                        'angle' => array(
                                'type' => 'slider',
                                'step' => 10,
                                'width' => 200
                        )
                )
        )
),

Note the range which defines the possible values as varying from -90 to 90. With the step property we indicate that we want to progress by increments of 10. The slider wizard is rendered like this:

The slider wizard

The slider wizard next to the input field