stmllr.net

Using the new TCA wizard "suggest" for autocompletion in BE fields of TYPO3 4.3

by on stmllr.net

There's a new type of wizard in the TYPO3 core called "suggest", which has been added to TCA with 4.3beta-1. This wizard adds a magic input field for autocompletion to fields of type "group" or "select", also called find-as-you-type. It helps to quickly find a record by typing its name/title in the suggest field, getting an AJAX dropdown list with all possible results. This article demonstrates how to implement this wizard in your TYPO3 extension.

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.

suggest wizard in action

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.

Field with suggest wizard in the BE

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

Tags

Comments

  1. Steffen Gebert

    Hi Steffen,

    what browser did you use? Usually cursor should be pointer, not the normal one. Or is this an older revision? ;-)

    Regards
    Steffen

  2. Steffen

    Good catch!
    I used a trunk version which was older than the 4.3-beta1 release. I wrote this article a week ago, but then decided to release it parallel to 4.3-beta1.

  3. Steffen Gebert

    Okay.. so I'm settled down again :)

    Steffen

  4. Steffen

    Aah, now I see. You mean Bug #11990.

  5. Steffen

    Meanwhile, the TSconfig part of the suggest feature has been integrated into the official docs (doc_core_tsconfig)

  6. Romain Ruetschi

    To use the suggest wizard in FlexForms simply copy/paste what follows right before the element's closing tag:

    <wizards type="array">
        <suggest>
            <type>suggest</type>
        </suggest>
    </wizards>

  7. Elías

    Only one tip for the people who is looking for it.

    If you use select instead of group, You must use the 'allowed' property that was not mandatory before.

    Nice article, thanx

  8. Peter

    Any hints on how to build an own renderFunc for the results?

  9. Steffen

    Have a look at the function renderRecord() in t3lib/tceforms/class.t3lib_tceforms_suggest_defaultreceiver.php
    This function calls a user function you give in renderFunc and lets you manipulate the data row.

    I am sorry that I don't have an example at hand.

  10. Rainer

    This autocompleter is a good idea!
    But I'am looking for a solution to admin recipes and its ingredients with quantity. In this case I have to use IRRE (because the ingredient has also quantity.
    Any ideas?

    Rainer

  11. Rainer

    Hi,

    it seems that the wizard dont work if maxitems=1.
    In this case only one select box appears and the hit of the suggester will be transfer to it.

    Here my code:
    'config' => array (
    'type' => 'select',
    'size' => '15',
    'foreign_table' => 'tx_XXX_zutat',
    "foreign_table_where" => " ORDER BY title",
    'eval' => 'required',
    'allowed' => 'tx_XXX_zutat',
    'minitems' => 0,
    'maxitems' => 1,
    'wizards' => array(
    'suggest' => array(
    'type' => 'suggest',
    'maxItemsInResultList' => 25,
    ),
    ),

  12. Steffen

    Maybe using 'db' for type instead of 'select' helps?

  13. Andy

    When I added the code to the tca.php, the changes didn't work, I had to add the
    'wizards' => array(
      'suggest' => array(
        'type' => 'suggest',
      ),
    ),

    to the ext_tables.php to make the wizard work. I'm using TYPO3 4.4.2

  14. Laurent

    Just in case, an example for tt_news :

    In TsConfig :
    TCEFORM.tt_news.yourfield.suggest.default {
      pidList = 62
    }

    In tca.php
    [...]
    'wizards' => array(
      'suggest' => array(
        'type' => 'suggest',
      )
    )
    [...]

    Dont forget the suggest.default :)

  15. Frank Fischer

    Just found out, that suggest doesn't work with "foreign_table_where"-conditions with markers like "###PAGE_TSCONFIG_IDLIST###". Only the explicit csv-list works in that case.

Add a comment

Comments are moderated and need to approved. Please be patient.