Record manipulation happens through two functions:

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.

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
}

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.