Channel Field Model

Required

Optional

Get a Channel Field

Field #4 is the “About Images” field in the sample installation.

ee('Model')->get('ChannelField', 4)->first();

Change a field name

// Get the field object.  #4 is the About Images field.
$field = ee('Model')->get('ChannelField', 4)->first();

// Change the title using the parameter.
$field->field_name = 'new_field_name';

// Validate and Save.
$result = $field->validate();

if ($result->isValid())
{
  $field->save();
}

Get the Channels the Field is used in

Note that this only finds channels where fields were assigned individually and not when included within a field group.

// Get the field object.  #4 is the About Images field.
$field = ee('Model')->get('ChannelField', 4)->first();

// Get the Channel's object using the Channel relationship.
$channels = $field->Channels;

// Returns an array of channel IDs.
$channel_ids = $channels->pluck('channel_id');

// As one line:
 $channel_ids = ee('Model')->get('ChannelField', 4)->first()->Channels->pluck('channel_id');

Create a Basic New Field

$field = ee('Model')->make('ChannelField');

// Set required fields.
$field->site_id     = ee()->config->item('site_id');
$field->field_name  = 'my_field_name';
$field->field_label = 'Field Label';
$field->field_type  = 'text';
$field->field_list_items  = '';
$field->field_order = 1;

// Set field-specific settings
$settings = $field->getSettingsValues();
$settings['field_settings']['field_show_file_selector'] = 'y';
$field->setProperty('field_settings', $settings['field_settings']);

// Validate and Save.
$result = $field->validate();

if ($result->isValid())
{
  $field->save();
}

// Field ID is now available.
$field->field_id;

Field types Relationships, Grid and Fluid require additional steps. Their data will be NULL.

Add Field to a Field Group

// Get an existing field.
$field = ee('Model')->get('ChannelField', 4)->first();

// Add the field groups by ID.  Note the plural differences. This overwrites any existing assignments.
$field->ChannelFieldGroups = ee('Model')->get('ChannelFieldGroup', array(1,2))->all();

// Validate and Save.
$result = $field->validate();

if ($result->isValid())
{
  $field->save();
}

Populate a field compatible with list field types

For fields like Checkboxes, Multi Select, Radio Buttons, Select Dropdown and Selectable Buttons there are three ways to populate their options: value-labels pairs, manually or from other channel.

// populate manually
$field->setProperty('field_list_items', "first\nsecond\nthird");
// Validate and Save.

// populate with value-labels pairs
$checkboxes_settings = array(
            'value_label_pairs' => array('winner' => 'first', 'player' => 'second', 'loser' => 'third')
            );
// change field settings
$changing_settings = $field->getSettingsValues()['field_settings'];
foreach ($checkboxes_settings as $s => $s_value) {
            $changing_settings[$s] = $s_value;
        }
$field->setProperty('field_settings', $changing_settings);
// Validate and Save.

// or populate from other channel field
$field->setProperty('field_pre_populate','y'); // default is 'n'
$field->setProperty('field_pre_channel_id',4); //channel id
$field->setProperty('field_pre_field_id',80); // field id
// Validate and Save.

Create a relationship field

//Relationships with channel #4

//all properties are required
$relata_properties = array(
        'field_label' => 'relata',
        'field_name' => 'relata',
        'field_type' => 'relationship',
        'field_list_items' => ''
);

//all settings are optional
$relata_settings = array(
    'channels' => array(4), // if missing relates to all channels
    'expired' => true, // if missing defaults to false
    'future' => true, // if missing defaults to false
    'categories' => array(), // if missing or empty allows relationships with all categories
    'authors' => array(), // if missing or empty allows relationships with all authors
    'statuses' => array('open'), // if missing or empty allows relationships with all statuses
    'order_field' => 'entry_date', // default is by title
    'order_dir' => 'desc', // default is ascending
    'display_entry_id' => null, //default is false
    'allow_multiple' => true, // default is true
    'rel_min' => 0,  //Minimum number of related entries
    'rel_max' => null  // Maximum number of related entries
);

$field = ee('Model')->make('ChannelField');

$site_id = ee()->config->item('site_id');
$field->site_id     = $site_id;
// field_order: increment the last field order number of fields belonging to this site
$ordernumber = 1 + ee('Model')->get('ChannelField')->filter('site_id',$site_id)->order('field_order', 'DESC')->first()->field_order;
$field->field_order = $ordernumber;

// field settings
$changing_settings = $field->getSettingsValues()['field_settings'];
foreach ($relata_settings as $s => $s_value) {
    $changing_settings[$s] = $s_value;
}
$field->setProperty('field_settings', $changing_settings);

// field properties
foreach ($relata_properties as $p => $p_val) {
    $field->setProperty($p, $p_val);
}
// Validate and Save.