GravityForms: Custom Fields

This should be a quick and rough guide to implementing custom fields in GravityForms. This documents a lot of the stuff we found out while building the first version of Cloud File Uploader (a neat plugin to allow you to upload files directly to cloud providers on your forms).

GravityForms documentation on this subject is a little… lacking to say the least. And requires a little legwork to get some parts of the fields working as expected.

Create Field

While you can create the GF_Addon subclass, it doesn’t really get you much apart from listing inside of the GravityForms Settings UI. You should add your class here, but it is already documented by GravityForms themselves.

<?php

class GF_Test_Field extends GF_Field {
	public $type = 'id-test';

	public function get_form_editor_field_title() {
	    return esc_attr__( 'Test Field', 'pluginname' );
	}

	public function get_form_editor_field_settings() {
		// For a full list see the Field subclasses included with GravityForms
		return array(
			'conditional_logic_field_setting',
			'error_message_setting',
			'label_setting',
			'label_placement_setting',
			'description_setting',
			'css_class_setting',
		);
	}

	public function get_field_input( $form, $value = '', $entry = null ) {
		$form_id     = $form['id'];
		$id          = (int) $this->id;
		$field_id    = $is_entry_detail || $is_form_editor || 0 === $form_id ? "input_$id" : 'input_' . $form_id . "_$id";

		return <<<EOF
<input type="text" name="${field_id}" id="${field_id}" />
EOF;
	}

}

GF_Fields::register( new GF_Test_Field() );
Code language: HTML, XML (xml)

Add Field to a custom group

To add your field to it’s own group of fields, i.e for your company you will need to ensure the field group is created, if it hasn’t been already and ensure the form editor button is aded correctly.

To do so follow the rough PHP to add to your class

<?php

class GF_Test_Field extends GF_Field {

	// ... other stuff

	public function get_form_editor_button() {
		// This tells GravityForms exactly where to add our button
    	return array(
			'group' => 'invisible_dragon',
			'text'  => $this->get_form_editor_field_title(),
		);
	}

	public function maybe_add_field_group( $field_groups ) {
		foreach ( $field_groups as $field_group ) {
			// Some other plugin, or maybe even ourselves, has added the field group so we
			// don't need a duplicate
			if ( $field_group['name'] == 'invisible_dragon' ) {
				return $field_groups;
			}
		}

		// Field group doesn't exist so we need to add it, or GravityForms
		// won't render our button
		$field_groups[] = array(
			'name'   => 'invisible_dragon',
			'label'  => __( 'Invisible Dragon Addons', 'testplugin' ),
			'fields' => array()
		);

		return $field_groups;
	}

	public function add_button( $field_groups ) {
		// We need to do a double check and add our field group if it doesn't exist already
		$field_groups = $this->maybe_add_field_group( $field_groups );

		return parent::add_button( $field_groups );
	}

}
Code language: HTML, XML (xml)

Custom Field Attributes

You may commonly want to add custom attributes to your fields. For example in File Cloud File Uploader, we wish to choose the destination that field will upload files to.

GravityForms requires a hook into it’s main system, based on the tab you wish to add your field on, and based on some crafted Javascript, PHP and classnames matching, GravityForms displays the custom field on the page.

Note: The name you use for the setting much match!

<?php

class GF_Test_Field extends GF_Field {

	// other stuff...

	public function get_form_editor_field_settings() {
		return array(
			'conditional_logic_field_setting',
			'error_message_setting',
			'label_setting',
			'label_placement_setting',
			'description_setting',
			'css_class_setting',
			'cheese', // <-- notice we have selected a new setting
		);
	}

}

// You can do it like this, or using your GravityForms plugin subclass. Shown here as a function
// for simplicty's sake
add_action( 'gform_field_standard_settings', 'myplugin_standard_settings', 10, 2 );
add_action( 'gform_editor_js', 'myplugin_editor_script' );

function myplugin_standard_settings( $position, $form_id ) {
	//create settings on position 25 (right after Field Label)
	if ( $position == 25 ) {
	?>
		<li class="cheese field_setting">
			<label class="section-label" for="cheese">
				<?php esc_html_e( 'Cheese', 'myplugin' ); ?>
			</label>
			<select id="cheese" onchange="SetFieldProperty('cheese', this.value);">
				<option value=""><?= esc_html('-- Choose a destination --', 'myplugin'); ?></option>
				<option value="cheddar"><?= esc_html('Cheddar', 'myplugin'); ?></option>
				<option value="redl"><?= esc_html('Red Leicester', 'myplugin'); ?></option>
			</select>
		</li>
	<?php
	}
}

function myplugin_editor_script(){
	?>
	<script type='text/javascript'>
	//adding setting to fields of type "text"
	fieldSettings.select += ', .cheese';

	//binding to the load field settings event to initialize the checkbox
	jQuery(document).on('gform_load_field_settings', function(event, field, form){
		jQuery('#cheese').val(field.cheese);
	});
	</script>
	<?php
}
Code language: JavaScript (javascript)