Including a New Field Using the Add-On Framework

Introduction

In this article we will show how you can use the Add-On Framework to include a new field type which extends the GF_Field class.

Getting Started

Create a file with your add-on slug as the filename, this file will contain your plugin headers, define the version number, and handle including the actual add-on after Gravity Forms has loaded.

Here is the content of our simplefieldaddon.php file, excluding the plugin headers.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
define( 'GF_SIMPLE_FIELD_ADDON_VERSION', '1.0' );
 
add_action( 'gform_loaded', array( 'GF_Simple_Field_AddOn_Bootstrap', 'load' ), 5 );
 
class GF_Simple_Field_AddOn_Bootstrap {
 
    public static function load() {
 
        if ( ! method_exists( 'GFForms', 'include_addon_framework' ) ) {
            return;
        }
 
        require_once( 'class-gfsimplefieldaddon.php' );
 
        GFAddOn::register( 'GFSimpleFieldAddOn' );
    }
 
}

Define the Add-On class

  1. Create a second php file, in this case we have named it class-gfsimplefieldaddon.php.

  2. In this file you would include the Add-On Framework files by calling the following:

    1
    GFForms::include_addon_framework();

  3. Inherit the Add-On Framework by creating a new class which extends GFAddOn:

    1
    class GFSimpleFieldAddOn extends GFAddOn {}

  4. Add the class variables to configure the add-on.

    1
    2
    3
    4
    5
    6
    7
    protected $_version = GF_SIMPLE_FIELD_ADDON_VERSION;
    protected $_min_gravityforms_version = '1.9';
    protected $_slug = 'simplefieldaddon';
    protected $_path = 'simplefieldaddon/simplefieldaddon.php';
    protected $_full_path = __FILE__;
    protected $_title = 'Gravity Forms Simple Field Add-On';
    protected $_short_title = 'Simple Field Add-On';

  5. Add support for getting an instance of the add-on.

    When Gravity Forms is loading it initializes the add-ons, it does this by looping through each registered add-on and calling its get_instance function. Adding a get_instance function also helps other developers integrate with your add-on.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    private static $_instance = null;
     
    public static function get_instance() {
        if ( self::$_instance == null ) {
            self::$_instance = new self();
        }
     
        return self::$_instance;
    }

  6. Include the new field.

    To ensure that the new field is available when entry exports are performed we will include the file containing our fields class by overriding the pre_init() function.

    1
    2
    3
    4
    5
    6
    7
    public function pre_init() {
        parent::pre_init();
     
        if ( $this->is_gravityforms_supported() && class_exists( 'GF_Field' ) ) {
            require_once( 'includes/class-simple-gf-field.php' );
        }
    }

  7. Add any custom settings and tooltips required by the field.

    New settings can be defined by using the gform_field_standard_settings, gform_field_appearance_settings, and gform_field_advanced_settings hooks.

    Tooltips for those new settings can also be defined using the gform_tooltips filter.

    As these hooks are only required in the admin we can include them by overriding the init_admin() function like so:

    1
    2
    3
    4
    5
    6
    public function init_admin() {
        parent::init_admin();
     
        add_filter( 'gform_tooltips', array( $this, 'tooltips' ) );
        add_action( 'gform_field_appearance_settings', array( $this, 'field_appearance_settings' ), 10, 2 );
    }

    Define the tooltips function:

    1
    2
    3
    4
    5
    6
    7
    public function tooltips( $tooltips ) {
        $simple_tooltips = array(
            'input_class_setting' => sprintf( '<h6>%s</h6>%s', esc_html__( 'Input CSS Classes', 'simplefieldaddon' ), esc_html__( 'The CSS Class names to be added to the field input.', 'simplefieldaddon' ) ),
        );
     
        return array_merge( $tooltips, $simple_tooltips );
    }

    Define the field_appearance_settings function:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    public function field_appearance_settings( $position, $form_id ) {
        // Add our custom setting just before the 'Custom CSS Class' setting.
        if ( $position == 250 ) {
            ?>
            <li class="input_class_setting field_setting">
                <label for="input_class_setting">
                    <?php esc_html_e( 'Input CSS Classes', 'simplefieldaddon' ); ?>
                    <?php gform_tooltip( 'input_class_setting' ) ?>
                </label>
                <input id="input_class_setting" type="text" class="fieldwidth-1" onkeyup="SetInputClassSetting(jQuery(this).val());" onchange="SetInputClassSetting(jQuery(this).val());"/>
            </li>
     
            <?php
        }
    }

  8. Include any Scripts or Styles.

    See the Including Scripts and Styles when using the Add-On Framework article.

Define the Field class

  1. Create a third php file, in this case we have named it class-simple-gf-field.php and located it within our plugins includes directory.

  2. Within this file create a new class which extends GF_Field:

    1
    class Simple_GF_Field extends GF_Field {}

  3. Within the new class define the field type property:

    1
    public $type = 'simple';

  4. Override get_form_editor_field_title() to define the field title displayed in the form editor:

    1
    2
    3
    public function get_form_editor_field_title() {
        return esc_attr__( 'Simple', 'simplefieldaddon' );
    }

  5. Override get_form_editor_button() to add the field button to the form editor:

    1
    2
    3
    4
    5
    6
    public function get_form_editor_button() {
        return array(
            'group' => 'advanced_fields',
            'text'  => $this->get_form_editor_field_title(),
        );
    }

  6. Review the GF_Field article to see the other methods you can override to define your new fields appearance and functionality.

  7. At the end of the file, after your fields class, register the new field with Gravity Forms:

    1
    GF_Fields::register( new Simple_GF_Field() );

Download the Sample Add-On

The sample add-on used in the examples above, including inline documentation, is available from here:

https://github.com/richardW8k/simplefieldaddon