Backend API

This part of the API is used in the Backend. It is not well known to developers because TYPO3 lacks documentation about this part of the API. We will cover the major parts of the Backend API code in this section.

TCEforms

TCEforms is visually familiar to anyone who has used TYPO3.

From a developer's viewpoint, TCEforms is an automated way of presenting the content of a database table to the user in a form suitable for editing. TCEforms reads the table configuration array (or TCA) for the table and builds controls dynamically according to the information in the TCA. The TCA for each TYPO3 core table is stored in the TYPO3 core. Extensions provide additional TCA entries for each extension table. If a TCA entry is not provided for the table, the TYPO3 Install tool will complain about it.

TCEforms is the most complex TYPO3 class you can use from. Its API was never meant for external use, but it is still possible to do it. Though this will not be described in this book, developers can figure it out by looking at the file typo3/mod/user/ws/workspaceforms.php. This file makes use of TCEforms to create custom rendering of workspace records.

TCEmain

TCEmain is the TYPO3 record processor. It handles the following tasks:

• Record creation, deletion, updation, copying, and moving

• Clearing the cache

• Version creation, updating, and publishing

Though this list does not contain all the functions, the class contains over 100 functions and nearly 5500 lines of code. The class name for TCEmain is t3lib_TCEmain.

Most extension developers are interested in the first two entries from the list above. We will review these in the later sections.

Record Manipulation

Record manipulation happens through two functions:

• process_datamap()

• process_cmdmap()

These functions do not take any parameters. Parameters must be passed to TCEmain's start() function. If both functions need to be executed, then process_datamap() should be called first.

The process_datamap() function takes care of record creation and updates. The process_cmdmap() function moves, deletes, undeletes, localizes, and creates versions for records.

Both functions expect their data to be in a certain format. As often in TYPO3, data consists of arrays.

The process_cmdmap() function uses the following format for data:

$datamap = array(
$tableName => array(
$recordUid => array(
$fieldName => $fieldValue
)
)
);

Here, $tableName is the database table name. There can be any number of tables in the $datamap. The $recordUid variable is the unique identifier of the record (uid field in the database table). If $recordUid is a string and starts from NEW (followed by a random string), then a new record will be created in the database. $fieldName is a database field name (uid cannot be passed as a field). The $fieldValue variable is an unescaped (raw) field value. The process_cmdmap() function has additional useful features. For example, it is possible to create a page and its content elements at once. The $recordUid variable for the pages table will start with NEW, and pid field for each content element should have the same identifier. TCEmain will substitute pid values automatically. But do not try it with other fields, it will not work as it does with pid. You can also insert a record before another record. In this case, pid field should be a negative value of the other record's uid attribute.

After a record is created, it is possible to obtain record uid values from TCEmain. TCEmain's substNEWwithIDs attribute is an array where keys are NEW-style identifiers, and values are uid values for new database records.

The process_cmdmap() function has similar data format:

$cmdmap = array(
TCEmain, BE APIrecord, manipulating$tableName => array(
$recordUid => array(
$command => $command_data
)
)
);

The next table shows values for $command and the format of $command_data.

Command	Command data format
Move	uid of the page where the record will be moved
copy	uid of the page where the record will be copied
localize	uid of the record from the sys_language table
version	Complex;.beyond the purpose of this book.
delete	empty
undelete	empty

The following code example will create a page with a single text element and delete this page with the element.

require_once(PATH_t3lib . 'class.t3lib_tcemain.php');
$pid = 'NEW' . uniqid('');
$content_uid = 'NEW' . uniqid('');
$tstamp = time();
// Datamap for page and content
$datamap = array(
'pages' => array(
$pid => array(
'pid' => 1,
'title' => $GLOBALS['LANG']->getLL('my_page_title'),
'hidden' => 0,
// Next line says that page is "Standard"
'doktype' => 1,
'crdate' => $tstamp,
'tstamp' => $tstamp,
// Next line says what user created the page
'cruser_id' => $GLOBALS['BE_USER']->user['uid'],
// Set some permissions. See TSConfig document
'perms_userid' =>
$GLOBALS['BE_USER']->user['uid'],
'perms_groupid' => 0, // No group
'perms_user' => 31, // See TSConfig
'perms_group' => 27,
'perms_everyone' => 0,
)
),
'tt_content' => array(
$content_uid => array(
'pid' => $pid,
'header' =>
$GLOBALS['LANG']->getLL('content_title'),
'CType' => 'text',
'bodytext' => 'Hello, TYPO3!',
'crdate' => $tstamp,
'tstamp' => $tstamp,
'cruser_id' => $GLOBALS['BE_USER']->user['uid'],
'colPos' => 0
)
)
);
// Create TCEmain instance
$tce = t3lib_div::makeInstance('t3lib_TCEmain');
/* @var $tce t3lib_TCEmain */
$tce->start($datamap, null);
$tce->process_datamap();
if (count($tce->errorLog) != 0) {
// $tce->errorLog is an array of error messages
}
// Prepare cmdmap to delete created records.
// BE user must have 'recursive delete' enabled
// for this example!
$cmdmap = array();
foreach ($tce->substNEWwithIDs as $new => $uid) {
// $tce->substNEWwithIDs_table is like
// $tce->substNEWwithIDs but contains
// table names
$cmdmap[$tce->substNEWwithIDs_table[$new]][$uid] = array('delete' => '');
}
$tce = t3lib_div::makeInstance('t3lib_TCEmain');
/* @var $tce t3lib_TCEmain */
$tce->start(null, $cmdmap);
$tce->process_cmdmap();
if (count($tce->errorLog) != 0) {
// Process error messages
}

Clearing Cache

If an extension's work affects the content of the page in the FE, the extension must take care of clearing cache for the page. For example, if an extension generates new content, modifies existing content, or creates a record that should be displayed on the page, the page cache has to be cleared.

TCEmain is strictly BE code. But cache pages are written in the way that allows one to use them from FE as well.

There are several functions that can be used to clear cache. As extension developers, we are mostly interested in one. It is named clear_cacheCmd. This function accepts a single parameter. For our purpose, it should be page uid value.

A code example:

require_once(PATH_t3lib . 'class.t3lib_tcemain.php');
// Create TCEmain instance
$tce = t3lib_div::makeInstance('t3lib_TCEmain');
/* @var $tce t3lib_TCEmain */
$tce->clear_cacheCmd(123);

If more than one page has to be cleared, it has to be done in a loop.