stmllr.net

How does the suggest wizard work?

Whenever you type some characters in the suggest field, the wizard searches for records matching the label field of given tables and immediately presents a list of results (find-as-you-type). Therefore it scans the table column which was set in the "label"-field or "label_alt"-field given in the $TCA['ctrl'] section of the tables. That's for example the title field in the pages table or the header field in tt_content. The suggest wizard can be added to a group or select field like any other wizard by adding it to the $TCA['columns']['fieldname']['config'] section. At the time of writing this article, it's supposed to work only for database records: that means fields of type "group" having set 'internal_type' => 'db'or fields of type "select" having 'foreign_table' => tablename. Files and static items don't work ATM.

How to add the suggest wizard to a field of your extension?

The suggest wizard is added to a field like any other wizard in TCA. If you have no idea of using wizards yet, have a look at wizard section of the TYPO3 Core API documentation.
For the suggest wizard, there are two places for configuration: The $TCA['columns']['fieldname']['config'] section and page TSconfig.

A simple scenario for demonstration

There's an extension appended in this article for demonstration. The extension ships two new tables for articles and authors. To set the author in the article table, you can select records from the author table. Therefore the author field of articles not only shows a list of selectable authors, but also implements the new suggest wizard.

Downloading the example extension

If you like to see the wizard in action, you can download the example extension "Demonstrate the TCA suggest wizard (demo_suggest)".

The extension ships some sample data as a t3d file inside res/suggest_demo_dataset.t3d which can be imported with the import/export tool. You need to move this file into the fileadmin/ directory to be able to import the data into your TYPO3 installation.

Implementing the wizard

The below example code shows how to add the wizard to the "author" field of the table "tx_demosuggest_article" in TCA. In the "allowed" section, you need to add the table which should be searched for records. (When editing an article, you want to search for authors).

TCA (tca.php)

$TCA['tx_demosuggest_article']['columns']['author']['config'] => array(
    'type' => 'select',    
    'foreign_table' => 'tx_demosuggest_author',
    'allowed' => 'tx_demosuggest_author',    
    'size' => 10,    
    'minitems' => 0,
    'maxitems' => 100,
    'wizards' => array(
        'suggest' => array(    
            'type' => 'suggest',
        ),
    ),
);

There are some configuration options which can be set directly in the TCA-wizard section or by using pageTS. The below example limits the number of results to 5 and searches only in page 123:

TCA (tca.php)

$TCA['tx_demosuggest_article']['columns']['author']['config'] => array(
    (...)
    'wizards' => array(
        'suggest' => array(    
            'type' => 'suggest',
            'tx_demosuggest_author' => array(
                'maxItemsInResultList' => 5,
                'pidList' => '123',
            ),
        ),
    ),
);

These options can also be set in page TSconfig:

pageTS (TSconfig)

TCEFORM.suggest.tx_demosuggest_author {
  maxItemsInResultList = 5
  pidList = 123
}

Instead of setting these options for a certain table, you can also set a default value for any table:

pageTS (TSconfig)

TCEFORM.suggest.default {
  maxItemsInResultList = 5
}

Find a full list of all options in the TYPO3 Core API documentation. As long as 4.3 is not realeased, please refer to the corresponding section of pending documentation in TYPO3 wiki.

Of course you can also use this wizard in any table of the TYPO3 core. It is already implemented in the storage_pid field of pages.

Further Reading

• TYPO3 Core API Documentation (once 4.3 is released)
• Wizards configuration in TYPO3 Core API Documentation
• Pending documentation in the TYPO3 wiki (until 4.3 is finally released)