A Simple Guide To Develop A Fieldtype In ExpressionEngine

December 08, 2020Posted By: Amit Saini

Content Management SystemExpressionEngine

ExpressionEngine Fieldtype Overview

ExpressionEngine’s key functionality lies in its ability to facilitate the easy management of site data by non-technical individuals. This is achieved by introducing the Channel and Fields concept, where a channel serves as a grouping of various Field Types.

These Field Types can include Text Input, Textarea, Date, and more, and they are responsible for storing and organizing the data on your website.

ExpressionEngine Has The Following Built-In Field Types

Date
Duration
Email Address
File
File Grid
Fluid
Grid
Relationships
Rich Text Editor
Checkboxes, Radio Buttons, Select, Multiselect
Text Input
Textarea
Toggle
URL

While the existing Field Types often cover our data management needs on the website, there are situations where a unique Field Type with specific logic is required. In such instances, the creation of a custom Field Type becomes necessary.

To craft a custom Field, we adhere to the Addon file structure since Field Types are a component of Addons. To initiate this process, the first step is to select a name for the Fieldtype; for instance, “custom_field.”

Location Of Field Type File

The Field Type is stored in the same location as third-party add-ons. First, we establish a folder in “system/user/addons” with the name “custom_field” and place the Fieldtype file within it. It’s worth noting that the folder path may vary depending on the version of ExpressionEngine being used. The Fieldtype file should be named “ft.custom_field.php.” It’s important to emphasize that the folder name and the Fieldtype name are identical, with the only distinction being the addition of the “ft” prefix to the Fieldtype file. Now, let’s delve into the structure of the Fieldtype file.

File Structure

Below is the basic file structure of Fieldtype.

<?php

if (!defined('BASEPATH')) exit('No direct script access allowed');

class Custom_field_ft extends EE_Fieldtype {

    var $info = array(
        'name'    => 'Custom Field',
        'version' => '1.0'
    );

    function display_field($data) {
        return form_input(array(
            'name'  => $this->field_name,
            'id'    => $this->field_id,
            'value' => $data
        ));
    }

}

The provided code snippet serves the purpose of displaying an Input-type field within the Field list dropdown.

Now, let’s examine the code:

In the code, the “$info” variable contains vital information about the field type, such as its name, version, description, and more. This information is used to display details on the Add-ons list in the backend.
In the backend, the “display_field” function is responsible for rendering the Fieldtype, as demonstrated in the screenshot mentioned earlier. You have the option to return an HTML string representing the Fieldtype or utilize the “form_input” method.
It’s crucial to note that the Add-on folder should include an “addon.setup.php” file. This file is where you declare the compatibility of the field type, allowing site builders to switch between different Field Type compatibilities. For example, you can switch from a “text” field to an “email” field and vice versa.
There are other field-type functions that can be employed depending on the features of your field type. Some services are typically handled within the Fieldtype file. If your Fieldtype is of the Input type, you’ll need to validate and save the value of this field. To accomplish this, you override the built-in functions of the Fieldtype Class.

Function Details

Display_field($data)

The primary purpose of the field type is to implement the display field method, as it is the most crucial function. While other elements can be omitted, this particular function is mandatory.

function display_field($data)
{
    return "Custom Field";
}

Accepts_content_type($name) function

You can use this function to control backward compatibility. All Field Types initially support the ‘channel’ content type.

If we need to define compatibility with other content types, we override this method for more control.

Here is an example:

public function accepts_content_type($name)
{
    return ($name == 'channel' || $name == 'grid' || $name == 'fluid_field');
}

The above code allows the Fieldtype to work with ‘channel,’ ‘grid,’ and ‘fluid_filed.’ Other content types will be ignored for this field type.

Validate($data)

This function validates the field data, which is called before the field is stored. We can define custom validation and return True, False, or error messages based on your validation result.

Here is an example:

function validate($data)
{
    if (preg_match('/^#[a-f0-9]{6}$/i', $data)) {
        return true;
    } else {
        return "Value contains only characters or numbers";
    }
}

Save($data)

This function saves the returned field data. Here you can make any changes before saving the data. The returned value of this function is saved.

public function save($data)
{
    return $data;
}

Replace_tag($data, $params = array(), $tagdata = FALSE)

This function is called before the rendering tag. It replaces the field tag on the front end. Before showing the field data on the front end, we can make changes to the data.

Here is an example:

function replace_tag($data, $params = array(), $tagdata = FALSE)
{
    return "Prefix " . $data . " Suffix";
}

In the above example field, data will show on the front end with “Prefix” and “Suffix” concatenate strings.

FieldType Settings

The FieldType settings in FieldType have a global impact on both the backend and frontend. Some Field types, however, require specific configurations to function correctly. For instance, when dealing with the Input FieldType, you may need to define settings like maximum length, placeholder text, maximum value, minimum value, or custom settings.

To set these global configurations, ExpressionEngine (EE) offers built-in functions that can be customized. By overriding these functions, you can specify the types of settings required. EE provides functions for displaying and saving these global settings.

display_settings()

This function displays the Form of the field setting. We return the Form field in an array that displays our setting form using the Shared Form View format.

Here is an example:

function display_settings() {
    $settings = array(
        array(
            'title'  => 'Max Length',
            'desc'   => 'max_length_desc',
            'fields' => array(
                'max_length' => array(
                    'type'  => 'text',
                    'value' => '10',
                )
            )
        ),
        // ... you can define more fields here ...
    );

    return array(
        'field_options_custom_field' => array(
            'label'    => 'field_options',
            'group'    => 'custom_field',
            'settings' => $settings
        )
    );
}

On your Field manager, when you choose ‘custom_field,’ the above setting form will appear in the ‘field_options’ section.

save_settings($data)

Function saves the field type settings. We return the submitted data, and we can modify the provided data according to our requirements.

Here is an example:

public function save_settings($data)
{
    // do the stuff with $data
    return $data;
}

Conclusion

In the end, you have learned how to develop a Fieldtype in ExpressionEngine. In the above content, we explained only the basics of creating a Field Type with standard functions that are mostly used in any Field Type—Saving and validation of the data of field type and field settings.