Field Map FieldIntroductionParametersExampleHelpersget_field_map_fields()get_field_value()Uses
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
name string Required. Name of the field. Use it to retrieve saved data.label string Required. Field label. Will be displayed in the UItype string Required. Field type. Must be set to field_map for the Field Map fieldtooltip string Optional. Defaults to blank (no tooltip). Displays a question mark icon and a tooltip next to the field label.field_map arrayRequired. Array that defines the fields to be mapped.Each item in the field_map array has the following properties:name stringRequired. Name of the field to be mapped. To be used when retrieving the selected value.label stringRequired. Label to be displayed in the UI.required boolOptional. 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 stringOptional. 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.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.
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' => '
' . esc_html__( 'Map Fields', 'sometextdomain' ) . '
' . 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'] );
Uses
settings_field_map()field_map_table_header()field_map_title()get_mapped_field_name()settings_field_map_select()get_field_map_choices()
