Field Map Field Type

Introduction

The field_map type field, part of the Settings API, allows the user to map their form fields to fields you define, e.g. fields you will be sending to a third-party service such as a CRM.

Parameters

Param	Type	Description
name	string	Required. Name of the field. Use it to retrieve saved data.
label	string	Required. Field label. Will be displayed in the UI
type	string	Required. Field type. Must be set to field_map for the Field Map field
tooltip	string	Optional. Defaults to blank (no tooltip). Displays a question mark icon and a tooltip next to the field label.
field_map	array	Required. Array that defines the fields to be mapped.
validation_callback	(function)	Optional. Defaults to nothing (no callback). Calls a function during validation allow for custom validation logic. The example in the existing documentation page is good.

Field_Map

Each item in the field_map array has the following properties:

Prop	Type	Description
name	string	Required. Name of the field to be mapped. To be used when retrieving the selected value.
label	string	Required. Label to be displayed in the UI.
required	bool	Optional. Defaults to false. Possible values are true or false. Marks this field as required, which means it must be mapped to a form field.
default_value	string	Optional. Defaults to blank (nothing is pre-selected). Allowed values are field IDs. When specified, the form field drop down is pre-selected with the appropriate field.

Example

array(
    'title'  => esc_html__( 'This is the title for Section 1', 'sometextdomain' ),
    'fields' => array(
        array(
            'name'      => 'contactStandardFields',
            'label'     => esc_html__( 'Map Fields', 'sometextdomain' ),
            'type'      => 'field_map',
            'field_map' => $this->standard_fields_for_feed_mapping(),
            'tooltip'   => '<h6>' . esc_html__( 'Map Fields', 'sometextdomain' ) . '</h6>' . esc_html__( 'Select which Gravity Form fields pair with their respective third-party service fields.', 'sometextdomain' )
        ),
    ),
),

Here’s the function being used to define the fields for the field_map property.

public function standard_fields_for_feed_mapping() {
    return array(
        array(
            'name'          => 'first_name',
            'label'         => esc_html__( 'First Name', 'sometextdomain' ),
            'required'      => true,
            'field_type'    => array( 'name', 'text', 'hidden' ),
            'default_value' => $this->get_first_field_by_type( 'name', 3 ),
        ),
        array(
            'name'          => 'last_name',
            'label'         => esc_html__( 'Last Name', 'sometextdomain' ),
            'required'      => true,
            'field_type'    => array( 'name', 'text', 'hidden' ),
            'default_value' => $this->get_first_field_by_type( 'name', 6 ),
        ),
        array(
            'name'          => 'email_address',
            'label'         => esc_html__( 'Email Address', 'sometextdomain' ),
            'required'      => true,
            'field_type'    => array( 'email', 'hidden' ),
            'default_value' => $this->get_first_field_by_type( 'email' ),
        ),
    );
}

The above code would render the following:

Helpers

The following functions may come in helpful when interacting with the field_map field type during feed processing.

get_field_map_fields()

Retrieves the individual field_map fields from the meta property of the Feed Object for the supplied field name.

$contact_standard_fields = $this->get_field_map_fields( $feed, 'contactStandardFields' );

$feed Feed Object
The Entry Object to be checked.
$name string
The name property of the field_map field to retrieve the mapped fields for.
Returns array

An array containing the field names as the keys to the mapped form field ID or entry meta key.

get_field_value()

Retrieves the specified form field or entry meta value. See Accessing Mapped Field Values During Feed Processing for more details.

$first_name = $this->get_field_value( $form, $entry, $contact_standard_fields['first_name'] );