ItemManager API Reference - Working with fields

Erstellt am: Tuesday 27 December 2016  |  Letzte Änderung am: Wednesday 15 August 2018

This article offers a brief description of how you can create, edit and delete fields programmatically.

Use FieldMapper class if you want to create or edit category fields programmatically. Normally, you do not really need the methods of this class, because you can comfortably assign any fields to your categories in the admin area with ItemManager interface. However, the knowledge about this functionality can be helpful if you intend to develop your own plugin, specially if you want to develop automatic installation routines for your plugin. An example is ImForms plugin that based on ItemManager API.

Creating an instance of the FieldMapper class:

$fieldMapper = new \FieldMapper();

Initialize all the category fields, even if none have yet been created:


Get a specific field from a category:

// Gets field by id
$field = $fieldMapper->getField(2);
// Or gets field by name
$field = $fieldMapper->getField('name=your_field_name');

Sort the fields of a specific category by an attribute:

$filteredFields = $fieldMapper->filterFields('position', 'ASC');

Get all the fields of a category:

$fields = $fieldMapper->fields;

Check if a fields file exist:

if(true === $fieldMapper->fieldsExists($category_id)) {
    echo 'The category fields exist!';

Create a new fields file (Only the file is created but no fields).

if(true !== $fieldMapper->fieldsExists($category_id)) {

For creating new fields the ItemManager offerings two methods, there is a first one:


... where the $fields parameter is an array of the field data:

$fields = array(
    'cat' => $category->id, // The id of the category to which the fields should belong

    // Field 1
    // 'cf_0_id'      => $field_id, Field id, if the field already exists
    'cf_0_key'   => 'description', // Field name. No special characters (underscores allowed)
    'cf_0_label' => 'Description', // Field label
    'cf_0_type'  => 'editor', // Field type
    'cf_0_options' => '', // dropdown fields only
    'cf_0_value' => '', // Field value

    // Field 2
    // 'cf_1_id'      => $field_id, Field id, if the field already exists
    'cf_1_key'   => 'date', 
    'cf_1_label' => 'Date',
    'cf_1_type'  => 'datepicker',
    'cf_1_options' => '',
    'cf_1_value' => '',

    // Field 3
    // 'cf_3_id'      => $field_id, Field id, if the field already exists
    'cf_2_key'   => 'images',
    'cf_2_label' => 'Images',
    'cf_2_type'  => 'fileupload',
    'cf_2_options' => '',
    'cf_2_value' => '',

Remember to set a field-ID parameter cf_*_id, if the field already exist (on fields update).

The second method is more programmatically:

$newField = new \Field($category->id);
$newField->set('name', 'my_field_name');
$newField->set('type', 'text');
$newField->set('label', 'Your field label');
$newField->set('position', 3);
$newField->set('default', '');
$newField->set('options', '');
$newField->set('info', '');

Backup & Delete fields file

$imanager->config->createBackup(IM_FIELDS_DIR, $category->id, IM_FIELDS_FILE_SUFFIX);

Delete a single field:

$myField = $fieldMapper->getField('name=your_field_name'));
// check if the field exists
if($myField) {

Also note if you delete fields of a category that already contain the content for the items. The field contents for existing items will not be deleted immediately, but marked for deletion and removed the next time the item is saved. Don't worry - The deleted contents is no longer used by ItemManager. This is not a bug, but a side effect of working without a database.

Have a look at the example script below, there I first create a category named Products and assign two custom fields to it - the first field named description and the second one named price:

imanager(); // Initialize IM

$category = new \Category();
$category->set('name', 'Products');
$category->set('slug', $category->name);
	echo "A new category $category->name was successfully created.<br>\r\n";

	$fieldMapper = new \FieldMapper();

	// Create Description field
	$newField = new \Field($category->id);
	$newField->set('name', 'description');
	$newField->set('type', 'editor');
	$newField->set('label', 'Product description');
	$newField->set('position', 1);
	$newField->set('default', '');
	$newField->set('options', '');
	$newField->set('info', '');
	if($newField->save()) {
		echo "The Description field was created successfully.<br>\r\n";

	// Create Price field
	$newField = new \Field($category->id);
	$newField->set('name', 'price');
	$newField->set('type', 'money');
	$newField->set('label', 'Price');
	$newField->set('position', 2);
	$newField->set('default', '0.00');
	$newField->set('options', '');
	$newField->set('info', '');
	if($newField->save()) {
		echo "The Price field was created successfully.<br>\r\n";

Autor: Bigin  |  Tags:  FrameworkPHPScriptsGetSimpleDevelopmentItemManager