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: - TRUEif setup was successful,- FALSEif 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) – TRUEif 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_typekey, and can include an optional- field_nameif 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_idin the- $field_dataarray to update an existing field, or omit- field_idto 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, (- intoptional)
- field_name, (- stringa-zA-Z0-9_- only)
- field_label, (- string)
- field_type, (- stringa valid fieldtype short name)
- field_order, (- int)
- field_instructions, (- string)
- field_required, (- stringy/n)
- field_search, (- stringy/n)
- field_is_hidden, (- stringy/n)
- field_fmt, (- string)
- field_show_fmt, (- string)
- field_text_direction, (- stringltr/rtl)
- field_maxl, (- int)
- and other fieldtype-specific settings, see the fieldtype’s display_settingsandsave_settingsmethods 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_data (array) – The field settings. Needs the following
keys: 
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_idis optional if you are creating a new field.- $field_typesis 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 ifFALSE
 - Returns: - View variables for the - admin/field_editview- Return type: - Array - Example Usage: - $vars = ee()->api_channel_fields->field_edit_vars(1, 2); return ee()->load->view('admin/field_edit', $vars, TRUE);