Functions reference

FieldFrame Documentation

There are a few things that most fieldtype extensions need to do: display field settings, display the field, and customize the template tag output. These are the key areas that FieldFrame aims to simplify.

Below is a list of the functions you can add to your fieldtype extension to accomplish these things.

Functions at a glance

update

Called when the fieldtype extension is first installed, or updated.

Arguments:
  • $from (string or bool) — previously-installed fieldtype version number, or FALSE if it’s a new install

display_site_settings

Add site-wide settings to the Fieldtype Manager within FieldFrame’s settings

Returns

HTML to be inserted into your fieldtype’s Settings block within the Fieldtype Manager

save_site_settings

Modify the site settings’ post data before it gets saved to the database.

Arguments:
  • $site_settings (array) — post data that came from any inputs you created in display_site_settings
Returns

Array with the modified post data

display_field_settings

Add custom settings to the Edit Field form

Arguments:
  • $field_settings (array) — previously-saved field settings
Returns

Associative array with the following optional keys:

  • cell1 (string) — HTML to be inserted in the same cell as the Field Type select
  • cell2 (string) — HTML to be inserted in the cell to the right of the Field Type select
  • rows (array) — additional rows to be inserted below the row with the Field Type select. Each element is a nested array with two elements which contain the HTML to be inserted in the left and right cells of a new row
  • formatting_available (bool) — determines whether the “Default Text Formatting for This Field” setting block should be available (FALSE by default)
  • direction_available (bool) — determines whether the “Text Direction” setting block should be available (FALSE by default)

display_cell_settings

Add custom cell settings to the FF Matrix Configuration setting within the Edit Field form

Arguments:
  • $cell_settings (array) — previously-saved cell settings
Returns

HTML to be inserted below the Cell Type select

save_field_settings

Modify the field settings’ post data before it gets saved to the database.

Arguments:
  • $field_settings (array) — post data that came from any inputs you created in display_field_settings
Returns

Array with the modified post data

save_cell_settings

Modify the FF Matrix cell settings’ post data before it gets saved to the database.

Arguments:
  • $cell_settings (array) — post data that came from any inputs you created in display_cell_settings
Returns

Array with the modified post data

display_field

Create the custom field HTML for the Publish form.

Arguments:
  • $field_name (string) — name you give your field input (e.g. “field_id_1”)
  • $field_data (string) — previously-saved field data
  • $field_settings (array) — the field settings
Returns

String of HTML to be inserted into the Publish form

display_cell

Create the custom FF Matrix cell HTML for the Publish form.

Arguments:
  • $cell_name (string) — name you give your cell input
  • $cell_data (string) — previously-saved cell data
  • $cell_settings (array) — the cell settings
Returns

String of HTML to be inserted into the FF Matrix cell in the Publish form

save_field

Modify the field’s post data before it gets saved to the database.

Arguments:
  • $field_data _ — the field’s post data _(since 0.9.5; used to be the field name)
  • $field_settings _ — the field settings _(since 0.9.2)
  • $entry_id (mixed) (only passed if Postponed saving is enabled) — the entry’s ID, or FALSE if the user clicked Preview on a new entry (since 1.0.5)
Returns

The modified post data

save_cell

Modify the FF Matrix cell’s post data before it gets saved to the database.

Arguments:
  • $cell_data (mixed) — the cell’s post data
  • $cell_settings (array) — the cell settings
  • $entry_id _ — the entry’s ID, or FALSE if the user clicked Preview on a new entry _(since 1.0.5)
Returns

The modified post data

display_tag

Modify the template tag output.

Note: This will get called in the same manner regardless of whether it’s being called for a field or an FF Matrix cell.

Arguments:
  • $params (array) — key/value pairs of the template tag parameters
  • $tagdata (string) — contents of the template between the opening and closing tags, if it’s a tag pair
  • $field_data (string) — the field data
  • $field_settings (array) — the field settings

Beyond the arguments sent to display_field, there are a few helper variables temporarily attached to the global $FF object at the time it is called:

You can access any of these variables like so:

global $FF;
$field_id = $FF->field_id;
Returns

String of template markup