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 notReturn 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 optionalfield_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 omitfield_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
andsave_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_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_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 ifFALSE
Returns: View variables for the
admin/field_edit
viewReturn type: Array
Example Usage:
$vars = ee()->api_channel_fields->field_edit_vars(1, 2); return ee()->load->view('admin/field_edit', $vars, TRUE);