GF_Field

IntroductionGetting StartedMain Functionalityget_form_editor_field_title()get_form_editor_button()get_form_editor_field_settings()is_conditional_logic_supported()get_field_input()get_field_content()validate()get_form_inline_script_on_page_render()get_form_editor_inline_script_on_page_render()get_value_save_entry()get_value_merge_tag()get_value_entry_detail()SanitizationInput SanitizationOutput SanitizationHelpersget_input_type()get_tabindex()get_conditional_logic_event()get_field_placeholder_attribute()get_input_placeholder_attribute()Core Field ClassesAdd-On Field Classes

Introduction

The GF_Field class provides basic functionality for developers when creating new fields for Gravity Forms. It facilitates the following:

Adding a button for the field to the form editorDefining the field title to be used in the form editorDefining which settings should be present when editing the fieldRegistering the field as compatible with conditional logicOutputting field scripts to the form editor and front-endDefining the field appearance on the front-end, in the form editor and on the entry detail pageValidating the field during submissionSaving the entry valueDefining how the entry value is displayed when merge tags are processed, on the entries list and entry detail pagesDefining how the entry value should be formatted when used in csv exports and by framework based add-ons

Getting Started

These are the first steps you』ll need to take to create a field using the Field Framework.

Creating a new class which extends GF_Field (Note: If your new field will have similar functionality to an existing field you can save some work by extending that field type instead e.g. GF_Field_Post_Image extends GF_Field_Fileupload)Add the $type variableRegister the field with Gravity Forms

Example:

123456class GF_Field_Phone extends GF_Field {     public $type = 'phone'; }GF_Fields::register( new GF_Field_Phone() );

Main Functionality

Now you have the basic field you can start defining its appearance and behaviour by overriding functions from GF_Field or whichever the class you extended.

The examples shown below are taken from various field types.

get_form_editor_field_title()

The default behaviour of get_form_editor_field_title() is to return the value of the $type variable, however, you may want the field in the form editor to use a different title or have the first letter uppercased in which case you will want to override this method.

public function get_form_editor_field_title() {}

Example:

public function get_form_editor_field_title() {    return esc_attr__( 'Phone', 'gravityforms' );}

get_form_editor_button()

The default behaviour of get_form_editor_button() is to return an associative array assigning the field to the standard_fields group using the value returned by get_form_editor_field_title() as the button text.

The built-in groups are standard_fields, advanced_fields, post_fields, and pricing_fields. See the How To Add A Custom Field Group When Using The Field Framework article for an example showing how you can define a new group.

public function get_form_editor_button() {}

Example:

public function get_form_editor_button() {    return array(        'group' => 'advanced_fields',        'text'  => $this->get_form_editor_field_title()    );}

get_form_editor_field_settings()

The default behaviour of get_form_editor_field_settings() is to return an empty array so you will want to override this method and return an array containing the class names of the settings you want to appear on your field in the form editor.

You can find a list of the available settings in the following articles:

General Field SettingsAppearance Field SettingsAdvanced Field Settings

You can also define your own custom settings by using the gform_field_standard_settings, gform_field_appearance_settings, and gform_field_advanced_settings hooks.

function get_form_editor_field_settings() {}

Example:

function get_form_editor_field_settings() {    return array(        'conditional_logic_field_setting',        'prepopulate_field_setting',        'error_message_setting',        'label_setting',        'label_placement_setting',        'admin_label_setting',        'size_setting',        'rules_setting',        'visibility_setting',        'duplicate_setting',        'default_value_setting',        'placeholder_setting',        'description_setting',        'phone_format_setting',        'css_class_setting',    );}

is_conditional_logic_supported()

The default behaviour of is_conditional_logic_supported() is to return false meaning the field can』t be used with conditional logic. Override this method returning true to allow the field to be used when configuring conditional logic rules.

public function is_conditional_logic_supported() {}

Example:

public function is_conditional_logic_supported() {    return true;}

get_field_input()

This method is used to define the fields inner markup, including the div with the ginput_container class. The default behaviour of get_field_input() is to return an empty string so you will want to override this method.

public function get_field_input( $form, $value = '', $entry = null ) {}

Parameters:

$form Form ObjectThe form object currently being processed.$value string|arrayThe field value from the $_POST or the resumed incomplete submission.$entry null|Entry ObjectNull or the entry object currently being edited.

Return:

The field』s inner markup. string

Example:

public function get_field_input( $form, $value = '', $entry = null ) {    $form_id         = $form['id'];    $is_entry_detail = $this->is_entry_detail();    $id              = (int) $this->id;     if ( $is_entry_detail ) {        $input = "";         return $input . '
' . esc_html__( 'Coupon fields are not editable', 'gravityformscoupons' );    }     $disabled_text         = $this->is_form_editor() ? 'disabled="disabled"' : '';    $logic_event           = version_compare( GFForms::$version, '2.4.1', '<' ) ? $this->get_conditional_logic_event( 'change' ) : '';    $placeholder_attribute = $this->get_field_placeholder_attribute();    $coupons_detail        = rgpost( "gf_coupons_{$form_id}" );    $coupon_codes          = empty( $coupons_detail ) ? '' : rgpost( "input_{$id}" );     $input = "

" .             "get_tabindex() . '/>' .             "get_tabindex() . '/> ' .             "" .             "

" .             "" .             "" .             "" .             "

";     return $input;}

get_field_content()

This method is used to define the fields overall appearance, such as how the admin buttons, field label, description or validation messages are included. Most fields won』t need to override this method, display only types such as Page, Section or HTML are examples of fields which do override the get_field_content() method.

1public function get_field_content( $value, $force_frontend_label, $form ) {}

Parameters:

$value string|array
The field value from the $_POST or the resumed incomplete submission.

$force_frontend_label boolean
Should the frontend label be displayed in the admin even if an admin label is configured. Default is false.

$form Form Object
The form object currently being processed.

Return:
The fields markup. string. Note: use the placeholder {FIELD} to define where the markup returned by get_field_input() should be included.

Example:

public function get_field_content( $value, $force_frontend_label, $form ) {    $form_id         = $form['id'];    $admin_buttons   = $this->get_admin_buttons();    $is_entry_detail = $this->is_entry_detail();    $is_form_editor  = $this->is_form_editor();    $is_admin        = $is_entry_detail || $is_form_editor;    $field_label     = $this->get_field_label( $force_frontend_label, $value );    $field_id        = $is_admin || $form_id == 0 ? "input_{$this->id}" : 'input_' . $form_id . "_{$this->id}";    $field_content   = ! $is_admin ? '{FIELD}' : $field_content = sprintf( "%s%s{FIELD}", $admin_buttons, $field_id, esc_html( $field_label ) );     return $field_content;}

validate()

Override this method to perform custom validation logic. This method is only used if the field passes the required validation (field is not empty), and any no duplicates validation.

1public function validate( $value, $form ) {}

Parameters:

$value string|array
The field value from the $_POST.

$form Form Object
The form object currently being processed.

Return:
This method does not return a value via a return statement. Return the validation result and message by setting the fields failed_validation and validation_message properties.

Example:

public function validate( $value, $form ) {    $regex = '/^D?(d{3})D?D?(d{3})D?(d{4})$/';    if ( $this->phoneFormat == 'standard' && $value !== '' && $value !== 0 && ! preg_match( $regex, $value ) ) {        $this->failed_validation = true;        if ( ! empty( $this->errorMessage ) ) {            $this->validation_message = $this->errorMessage;        }    }}

get_form_inline_script_on_page_render()

Override this method to include scripts with the form init scripts on page render. The init scripts are usually included immediately after the form in the page body.

Note: