HowTo: Enable ExpressionEngine 2 custom field settings

Planning on developing ExpressionEngine 2 custom fields which have their own custom settings — then this quick post is for you.

EE2 (builds 20091207 and 20091211) have custom field custom settings disabled so before you can add your own settings there are a few core hacks that need to be applied. The hacks below will appear in a future update of EE2 so your custom field should continue to work.

Here’s the modifications you’ll need to apply:

Add a new table col titled field_settings to exp_channel_fields and set the data type to ‘text’
In /system/expressionengine/controllers/cp/admin_content.php around line 4514 (line numbers depends on your build) Uncomment:
```
$native_settings['field_settings'] = base64_encode(serialize($ft_settings));
```

Next you’ll need to tell EE what your custom settings are by returning an associative array in the save_settings method. I prefer to submit my custom settings in their own array which makes them easier to manage.

The display_settings method creates the settings form. A simple example:

/**
 * Display the settings form for each custom field
 * 
 * @access public
 * @param $data mixed Not sure what this data is yet :S
 * @return string Override the field custom settings with custom html
 * 
 * In this case we add an extra row to the table. Not sure how the table is built
 */
public function display_settings($data)
{
    // Add a table row to the settings table
    $this->EE->table->add_row(
        // row header
        Custom Configuration,
        // row content
        // $data includes our custom setting
        form_dropdown('my_field_field_settings[setting_1]',
                               array(1 => "Option 1", 2 => "Option 2"),
                               $data['setting_1'])
    );
}

When the form is submitted return the my_field_field_settings POST array as the custom settings array.

/**
 * Save the custom field settings
 * 
 * @param $data array Not sure what this is yet, probably the submitted post data.
 * @return boolean Valid or not
 */
public function save_settings($data)
{
    // return the custom field settings array
    // the array keys will become their own settings keys in $this->settings
    return $this->EE->input->post('my_field_field_settings');
}

The custom field settings are available in the $this->settings array when a new instance of the custom field class is created. You will need to access these settings when displaying the custom field in the publish form.

/**
 * Display the field in the publish form
 * 
 * @access public
 * @param $data String The field content
 * @return String The custom field HTML
 */
public function display_field($data)
{
    return $this->settings['setting_1'];
}

And there you have it — enabling custom field settings in EE2.

For more custom settings code examples check out NSM TinyMCE.

Comments

The following 4 people were compelled to have their say. We encourage you to do the same.

Christopher Imrie said on Wednesday 16th December, 10:46am: 1

Excellent. I’ve been converting my fieldtypes to EE2.0 and this was a major roadblock.

Thanks for the walkthrough
Leevi Graham said on Wednesday 16th December, 11:08am: 2

@Christopher: No worries. I’l try and put together a full tutorial going through each step in the near future. Keep an eye on this post as there will likely be updates as the API changes.
iain Urquhart said on Thursday 17th December, 10:36pm: 3

Thanks for the tip Leevi,

I just put my first fieldtype together and for the settings I ended up using $data[’field_list_items’] to hold the settings value… Bit of a hack but seems to work for the time being.
Leevi Graham said on Thursday 17th December, 11:18pm: 4

@Iain: Ah the good ol’ days. I remember storing all kinds of settings in unused cols in the custom field table.

Your approach is probably a good one until the API is actually published.