ExpressionEngine® 3 User Guide

Legacy Documentation

You are using the documentation for version 3.5.17. Go here for the latest version or check here for your available upgrades to the latest version.

ExpressionEngine Channel Fields API

Calling the Class

class Api_channel_fields

The Channel Fields class is called with the api->instantiate() function:

ee()->load->library('api'); ee()->legacy_api->instantiate('channel_fields');

Function Reference

Fetch all Fieldtypes

Api_channel_fields::fetch_all_fieldtypes()

Goes through all fieldtype files, includes them (using include_handler()), and returns an array of all found fieldtypes:

ee()->api_channel_fields->fetch_all_fieldtypes();
Returns:Nested associative arrays of fieldtype data (see below)
Return type:Array

Example of returned data:

array(
    'fieldtype_shortname' => array(
        'path'    =>  (string) File Path,
        'file'    =>  (string) Filename,
        'name'    =>  (string) Human readable name,
        'class'   =>  (string) Class Name,
        'package'   =>  (string) Package name
    ),
    'fieldtype_shortname2' => array(...),
);

A package name is only returned if the fieldtype comes from a third party

Fetch installed Fieldtypes

Api_channel_fields::fetch_installed_fieldtypes()

This method is identical to fetch_all_fieldtypes, but the returned array is limited to fieldtypes that have been installed by the user:

ee()->api_channel_fields->fetch_installed_fieldtypes();
Returns:Nested associative arrays of installed fieldtype data. Adds in version number and fieldtype ID.
Return type:Array

Include Fieldtype Class

Api_channel_fields::include_handler($field_type)

This method includes the class that is responsible for a certain fieldtype, and adds it to a list of known fieldtypes. Do not include fieldtypes manually as it may cause ExpressionEngine to not recognize them:

ee()->api_channel_fields->include_handler((string) $field_type);
Parameters:
  • $field_type (string) – Name of the fieldtype to include (e.g. ft.**field_name**.php)
Returns:

Name of the fieldtype’s class.

Return type:

String

Setup Fieldtype Class

Api_channel_fields::setup_handler($field_type)

This method prepares resets the fieldtype class and its settings. It must be called before a fieldtype is used:

ee()->api_channel_fields->setup_handler((string) $field_type);
Parameters:
  • $field_type (string) – Name of the fieldtype to include (e.g. ft.**field_name**.php)
Returns:

TRUE if setup was successful, FALSE if not

Return type:

Boolean

Setup Entry Settings

Api_channel_fields::setup_entry_settings($channel_id, $entry_data[, $bookmarklet = FALSE])

This method will properly populate the settings array for all fields in the specified channel. It returns an array of all field settings, and is typically used before the Channel Entries API’s submit_new_entry() method:

ee()->api_channel_fields->setup_entry_settings((string) $channel_id, (array) $entry_data, (bool) $bookmarklet);
Parameters:
  • $channel_id (int) – ID of the channel the entry is in
  • $entry_data (array) – Associative array of entry data
  • $bookmarklet (boolean) – TRUE if you need the data to be setup for a bookmarklet
Returns:

Nested array of field settings for a channel with data

Return type:

Array

Set Fieldtype Settings

Api_channel_fields::set_settings($field_id, $settings)

This method is used to assign additional settings to a fieldtype. This may be any data that a fieldtype developer may need to use in their fieldtype. The settings array must include a field_type key, and can include an optional field_name if used in a channel context:

ee()->api_channel_fields->set_settings((string) $field_id, (mixed) $settings);
Parameters:
  • $field_id (string) – ID of the field
  • $settings (mixed) – Array of settings to replace the original settings with
Return type:

Void

Get Fieldtype Settings

Api_channel_fields::get_settings($field_id)

This method gets the settings of an individual field:

ee()->api_channel_fields->get_settings((string) $field_id);
Parameters:
  • $field_id (string) – ID of the field
Returns:

Array of settings or an empty array if that field doesn’t exist

Return type:

Array

Call a Fieldtype Method

Api_channel_fields::apply($method[, $parameters = array()])

This is a convenience method to call a fieldtype after it has been setup. It will automatically setup the proper third party paths and handle PHP4’s pass-by-reference quirks. It acts on the last fieldtype that was passed to setup_handler(). It takes an array of parameters:

ee()->api_channel_fields->apply((string) $method, (mixed) $parameters);
Parameters:
  • $method (string) – Name of the method to run
  • $parameters (mixed) – Parameters to send to the method
Returns:

The return value of the fieldtype function that was called.

Return type:

Mixed

Example Usage:

$parameters = array(
    'foo'       => 'Dog',
    'bar'       => 'Cat'
);

ee()->api_channel_fields->setup_handler('my_fieldtype');
echo ee()->api_channel_fields->apply('my_method', $parameters);

Create or Update a Channel Field

Api_channel_fields::update_field($field_data)

This creates a new channel field or updates an existing field. Include a field_id in the $field_data array to update an existing field, or omit field_id to create a new one.

ee()->api_channel_fields->update_field((array) $field_data);
Parameters:
  • $field_data (array) – The field settings. Needs the following keys: group_id, site_id, field_name, field_label, field_type, field_order, and also fieldtype-specific settings, e.g. text_field_text_direction
Returns:

The field_id of the updated/created field.

Return type:

String

Values that may be passed in the $field_data array include:

  • group_id, (int)
  • field_id, (int optional)
  • field_name, (string a-zA-Z0-9_- only)
  • field_label, (string)
  • field_type, (string a valid fieldtype short name)
  • field_order, (int)
  • field_instructions, (string)
  • field_required, (string y/n)
  • field_search, (string y/n)
  • field_is_hidden, (string y/n)
  • field_fmt, (string)
  • field_show_fmt, (string)
  • field_text_direction, (string ltr/rtl)
  • field_maxl, (int)
  • and other fieldtype-specific settings, see the fieldtype’s display_settings and save_settings methods for more options

Example Usage:

$field_data = array(
    'group_id' => 1,
    'field_name' => 'blog_body',
    'field_label' => 'Body',
    'field_type' => 'text',
    'field_order' => 10,
    'field_required' => 'y',
    'field_search' => 'y',
    'field_is_hidden' => 'n',
    'field_instructions' => '',
    'field_maxl' => 128,
    'text_field_fmt' => 'none',
    'text_field_show_fmt' => 'n',
    'text_field_text_direction' => 'ltr',
    'text_field_content_type' => 'all',
    'text_field_show_smileys' => 'n',
    'text_field_show_glossary' => 'n',
    'text_field_show_spellcheck' => 'n',
    'text_field_show_file_selector' => 'n',
);

ee()->api_channel_fields->update_field($field_data);

Field Settings Variables

Api_channel_fields::field_edit_vars($group_id[, $field_id = FALSE[, $field_types = FALSE]])

This method supplies the view variables for field settings in the Edit/Create Field screen. This is used prior to and in conjunction with api_channel_fields->update_field(). $field_id is optional if you are creating a new field. $field_types is optional, and is an array of field types to display. By default, all field types are shown in the view:

ee()->api_channel_fields->field_edit_vars((int) $group_id, (int) $field_id, (array) $field_types)
Parameters:
  • group_id (int) – Group to add/edit field
  • $field_id (int) – Field ID if you’re editing, FALSE if it’s new
  • $field_types (array) – Array of field types to present as field_type_options, will show all valid field types if FALSE
Returns:

View variables for the admin/field_edit view

Return type:

Array

Example Usage:

$vars = ee()->api_channel_fields->field_edit_vars(1, 2);
return ee()->load->view('admin/field_edit', $vars, TRUE);