Enhanced Fieldtype Features Development

Working with Live Preview

In order for your fieldtype to render in a template under live preview, it needs to be able to render using data from the publish form, which is essentially your fieldtype’s POST data. You will not access your data from $_POST, your fieldtype’s data should be sent automatically to your replace_tag() method. If you’re missing any data, you can access the entry’s entire preview data via the LivePreview service.

This means if your fieldtype does extra processing before your data is saved and your replace_tag() method expects data in a different format than what is returned directly from the publish form, you’ll need to make accommodations.

For instance, say your fieldtype has inputs that look like this:

<input type="text" name="field_id_1[text1]">
<input type="text" name="field_id_1[text2]">

And your save() and replace_tag() routines looks like this:

function save($data)
{
    // Concatenate this data to save in the database
    return $data['text1'] . $data['text2'];
}

function replace_tag($data)
{
    // Data is preformatted, just return it!
    return $data;
}

You may want to change your replace_tag() routine to format its data on the fly:

function replace_tag($data)
{
    // Looks like we're in live preview, reformat our data for presentation
    if (ee('LivePreview')->hasEntryData())
    {
        return $data['text1'] . $data['text2'];
    }

    return $data;
}

$(document).trigger('entry:preview');

$(document).on('entry:preview-open', function(event) {
  // ...
});

Displaying field data in Entry Manager

Custom fields can display their data inside the Entry Manager through 3 possible ways:

1. Declare public $has_array_data = false; OR

2. Add implements ColumnInterface to fieldtype class definition.

   use ExpressionEngine\Library\CP\EntryManager\ColumnInterface;
   class Google_maps_ft extends EE_Fieldtype implements ColumnInterface {
   

   OR

3. Declare public $entry_manager_compatible = true; and implement renderTableCell method

Example:

class Google_maps_ft extends EE_Fieldtype
{
    public $has_array_data = true;

    public $entry_manager_compatible = true;

    /*.....*/

    /**
    * Implements EntryManager\ColumnInterface
    */
    public function renderTableCell($data, $field_id, $entry)
    {
        if (!empty($data)) {
            list($latitude, $longitude, $zoom) = explode('|', $data);
            return "<a href=\"https://www.google.com/maps/@{$latitude},{$longitude},{$zoom}z\" target=\"_blank\">View on map</a>";
        }
        return '';
    }

    /**
    * Allows HTML in the column content
    */
    public function getTableColumnConfig()
    {
        return [
            'encode' => false
        ];
    }

    /* .... */

}

Entry cloning support

ExpressionEngine has the ability to clone existing entries using the “Clone to New Entry” option on the entry editing page. Most fieldtypes do not need to do anything special to support this feature.

However, if the fieldtype you are developing saves data to its own database table, you might need to tell it to save the rows as a submission for the new entry and not for the existing one.

You can do this by adding this check:

if (defined('CLONING_MODE') && CLONING_MODE === true) {
    //this is cloning request, add new rows
}

Conditional Fields support

Unless different specified directly, each fieldtype can be as data source for Conditional Fields via the default evaluation rules set. The default set is different depending on whether the fieldtype can hold text-like data or array-like data.

If the fiedltype has has_array_data property set to true, the default rules set is limited isEmpty and isNotEmpty.

If has_array_data is not set or set to false, it is being assumed that the fieldtype holds text data and the rules list is set to following:

'equal', 'notEqual', 'isEmpty', 'isNotEmpty', 'contains', 'notContains'

If the fieldtype is not designed to be used as the source for conditional field evaluation, it can be excluded by using this code:

public $supportedEvaluationRules = null;

If the fieldtype needs to support the list or evaluation rules that is different from default, it can specify supportedEvaluationRules property as array of rule name, e.g.

public $supportedEvaluationRules = ['isEmpty', 'isNotEmpty', 'contains', 'notContains'];

If certain rule needs to be pre-selected by default when adding new condition to the field, it’s name can be specified in defaultEvaluationRule property, e.g.

public $defaultEvaluationRule = 'contains';

namespace ExpressionEngine\Addons\ToggleField\EvaluationRules;
use ExpressionEngine\Service\ConditionalFields\EvaluationRules\AbstractEvaluationRule;
use ExpressionEngine\Service\ConditionalFields\EvaluationRules\EvaluationRuleInterface;

class TurnedOn extends AbstractEvaluationRule implements EvaluationRuleInterface
{
    public function evaluate($fieldValue, $expectedValue, $fieldSettings)
    {
        if (is_null($fieldValue)) {
            $fieldValue = $fieldSettings['field_default_value'];
        }
        return get_bool_from_string($fieldValue);
    }

    public function getConditionalFieldInputType()
    {
        return null;
    }
}

public $supportedEvaluationRules = ['turnedOn', 'turnedOff'];

File Manager support

When a file is referenced inside content, it can be in two different forms depending on if the file manager is running in compatibility mode or not. An example of this is when a file is chosen inside an RTE field via the filepicker. If the file manager is not running in compatibility mode, the file references in content will contain a file ID (e.g. {file:123:url} where 123 is the file ID). The file can also be referenced in content with a directory ID and file name (e.g. {filedir_2}filename.jpg) when in compatibility mode.

To parse both cases correctly, please use the ee()->file_field->parse_string() function.

ee()->load->library('file_field');
$data = ee()->file_field->parse_string($data);

If the fieldtype is using custom JavaScript for manipulating the files, be sure to make the code aware of the EE.fileManagerCompatibilityMode variable.

Implementing Filepicker for Rich Text Editor

If your add-on is operating as File Manager, you might want to make it available as file picker for RTE fields.

In order to achieve that, create file prefixed with rtefb. in add-on’s main directory, e.g. rtefb.my_addon.php. You can refer to the file in Filepicker add-on as an example.

The file’s class needs to implement ExpressionEngine\Library\Rte\RteFilebrowserInterface. The easiest way to achieve that is to extend ExpressionEngine\Library\Rte\AbstractRteFilebrowser abstract class and add code only for the functions that work differently from

Working with Front-End Editing

Most fieldtypes will work with Front-end content management out-of-the-box.

However there are some parameters that can be set in ft. to improve integration.

public $disable_frontedit = true;

public $size = 'large';

public $complex_data_structure = true;