EXT: KB TCA Section¶

Section container table¶

An entry looks like this:

'tx_kbnntpif_messages' => Array(
  'ctrl' => ....
   .....
  'columns' => Array(
  ...
    'parts' => Array (
      'exclude' => 1,
      'label' => 'LLL:EXT:kb_nntp_if/locallang_db.php:tx_kbnntpif_messages.parts',
      'config' => Array (
        'type' => 'user',
        'userFunc' => 'EXT:kb_tca_section/class.tx_kbtcasection.php:tx_kbtcasection->getSingleField_typeSection',
        'el' => array(
          'tx_kbnntpif_message_parts' => &$GLOBALS['TCA']['tx_kbnntpif_message_parts'],
        ),
      )
    ),
   ....

And in the ext_tables.sql file a line like:

parts int(11) unsigned DEFAULT '0' NOT NULL,

This example should be mostly self explanatory. You define a “section” called “parts”. The userFunc is the magic which will render the section. In el “el” array you have to place “key => value” pairs where each “key” MUST be the name of a valid TCA table – and the value of each key should be the TCA-config (the complete one containg ctrl and else) for this table. The “&” in front of the value ensures that a reference to the TCA-config is created instead of making a copy of the configuration.

The “&” is a MUST because possibly at the time this definition gets “loaded” the “message_parts” tables TCA is not loaded completely. If you would make a copy of the array (not using the & operator) and the TCA would get completed later one then the copied array would still stay in the same uncomplete state (Because only the original gets modified) – If you create a reference using the & operator the keys point to the same array in memory and will change synchron.

Section element table¶

Now as this field 'parts' only contains the count of the elements contained you may ask where the relation is stored. The answer is simple: As this is a 1:n relation like the child-parent relation between pages you have to place a “parent” pointer into the child (the section elment table)

This is done by adding a field like the following:

'tx_kbnntpif_message_parts' => Array(
  'ctrl' => ....
   .....
  'columns' => Array(
  ...
    'msgparent' => Array (
      'exclude' => 1,
      'label' => 'LLL:EXT:kb_nntp_if/locallang_db.php:tx_kbnntpif_message_parts.msgparent',
      'config' => Array (
        'type' => 'group',
        'internal_type' => 'db',
        'allowed' => 'tx_kbnntpif_messages',
        'show_thumbs' => '1',
        'size' => 1,
        'maxitems' => 1,
        'minitems' => 1,
      )
    ),

Into the table which will get used as section elements. You do not need to add the field to the “types” or “palette” configuration. When you do not add it an editor will not be able to “move” a section element from one main-record to another (Assign a section element to another record).

Please take care that the field has “maxitems” set to 1. Else it would be possible to place more than one relation inside and this is of course not working (Also pages can only have one parent).

You need to configure the field in the ext_tables.sql file like:

msgparent int(11) unsigned DEFAULT '0' NOT NULL,

The last step is to add the following configuration to the 'ctrl' sub- array of the section-elemnt table:

$TCA['tx_kbnntpif_message_parts'] = Array (
  'ctrl' => Array (
    ...
    'sectionParentField' => 'msgparent',
    ...

This is a rather simple configuration which enables the section to get displayed inside the container records. In the example with the NNTP messages I wanted to display “message_parts” inside “messages” and also “message_parts” inside “message_parts” (the recursion). To solve this you can also configure the 'ctrl' section like this:

$TCA['tx_kbnntpif_message_parts'] = Array (
  'ctrl' => Array (
    ...
    'sectionParentField' =>
      'tx_kbnntpif_messages' => 'msgparent',
      'tx_kbnntpif_message_parts' => 'partparent',
    ),
    'sectionAddWhere' => array(
      'tx_kbnntpif_messages' => ' AND partparent=0',
    ),
    ...

The “sectionParentField” property changed to an array and contains now 2 entries telling which one the parent-field field is depending on which record get's rendered actually. So when “message_parts” get rendered inside “messages” the “msgparent” field is considered as parent. But when “message_parts” get rendered inside “message_parts” again the “partparent” field is taken as valid parent field. This is required because you can not (should not) mix references to two different tables in the same field – else you can't do proper (fast) queries to fetch the elements. (I consider speed in the backend also as important – at least my customers do that :)

Another feature added in the above ext_tables.php code is the “sectionAddWhere” clause. You can use it to restrict the records which get selected as elements. In our case we only want to display elements in the “messages” table which are not a child of another “message_part” (have partparent set to 0).

If the later example seems too complicated rather start your tests without recursion and different parent tables – this will ease things a lot.

About the example¶

The above example is about a NNTP (Newsserver) interface for TYPO3. What you see is the “parts” field of the messages tables which contains all the MIME parts of a single NNTP/SMTP MIME message. As you probably know a MIME message (which are both NNTP and normal SMTP- Mails aka. E-mails) consits only of a header and a message mody. The body again can (but must not) consist of multiple parts encapsulated in a so called multipart-MIME message .

In this case I choose that the message parts – which can be simple plain texts or files – get embedded into the message as TCA section. If a mail only consists of a plain-text part only one element will get added. But if a message contains a text and 2 files for example then 3 parts will get created and listed below each other.

In the ext_tables.sql file you will have to add a line like:

parts int(11) unsigned DEFAULT '0' NOT NULL,

to satisfy TYPO3 which requires a real SQL table field for each configured TCA field. The field will hold the number of referenced elements like it is known from TYPO3 n:m tables (why are they called “ *m:m* ” in TYPO3 ???)