Examples

How to read an item from database

Reading an item from database is quite simple! If you have its ID just pass it to the constructor of the appropriate Item class and your done.

$articleLanguage = new cApiArticleLanguage($idartlang);

It could also be done for an existing item instance:

$articleLanguage->loadByPrimaryKey($idartlang);

It could also be done for an existing item instance using an arbitrary column:

$articleLanguage->loadBy('idartlang', $idartlang);

It could also be done for an existing item instance using a set of arbitrary columns:

$articleLanguage->loadByMany(array(
	'idart' => $idart,
	'lang' => $lang
));

How to access an items fields?

if ($articleLanguage->isLoaded()) {
	$title = $articleLanguage->getField('title');
}

How to modify an items fields?

$articleLanguage->setField('title', 'new title');

How to store an item?

$articleLanguage->store();

How to delete an item?

Commented

This feature is currently commented! Please use the collection to delete the item by ID.

$articleLanguage->delete();

How to read a collection of items from database

$articleLanguageCollection = new cApiArticleLanguageCollection();
$articleLanguageCollection->select();

/* @var $articleLanguage cApiArticleLanguage */
while (false !== $articleLanguage = $articleLanguageCollection->next()) {}

When selecting a collection of items you can define conditions all items have to satisfy:

$articleLanguageCollection->select('idart = 1');

How to iterate a collection of items from database

/* @var $articleLanguage cApiArticleLanguage */
while (false !== $articleLanguage = $articleLanguageCollection->next()) {}

How to read multiple values of single table?

If you want to read multiple values of a single table your first approach might lokk similar to this snippet:

// get current clients con_upload records
$uploadCollection = new cApiUploadCollection();
$uploadCollection->setWhere('idclient', cRegistry::getClientId());
$uploadCollection->query();

$uploadMap = array();
while (false !== $upload = $uploadCollection->next()) {
    $uploadMap[$upload->get('idupl')] = $upload->get('dirname') . $upload->get('filename');
}

Don't do that!

It's awfully slow due to the fact, that each iteration yields another database query.

A much more performant way to achieve this goal is as follows:

// get current clients con_upload records
$uploadCollection = new cApiUploadCollection();
$uploadCollection->addResultField('dirname');
$uploadCollection->addResultField('filename');
$uploadCollection->setWhere('idclient', cRegistry::getClientId());
$uploadCollection->query();
 
$fields['idupl'] = 'idupl';
$fields['dirname'] = 'dirname';
$fields['filename'] = 'filename';
$table = $uploadCollection->fetchTable($fields);

$uploadMap = array();
foreach ($table as $key => $item) {
    $uploadMap[$item['idupl']] = $item['dirname'] . $item['filename'];
}

How to read values of multiple tables or how to use join partners?

In order to be able to read values of multiple tables with a single statement, references between tables have to be defined as "join partners". To do so, just define the reference to another table in the collection constructor.

Join partners are always the collection classes name!

class FirstCollection extends ItemCollection {
    public function __construct() {
		...
		// set the join partners so that joins can be used via link() method
        $this->_setJoinPartner('SecondCollection');
    }
}

When SecondCollection is known to FirstCollection as join partner you can link to it as shown in the next snippet. The name of the collection should be used as table name (which is in fact an alias) in order to avoid ambiguities. These aliases are case insensitive as they are always transformed to lowercase.

$coll = new FirstCollection();
$coll->link('SecondCollection');
$coll->addResultField('FirstCollection.idfirst');
$coll->addResultField('SecondCollection.idsecond');
$coll->query();

The created JOIN is a LEFT JOIN! The ON clause is automatically generated using the primary or foreign key respectivly.