bookmark_bordergeneric_map Field

Introduction

The generic_map field type, part of the Settings API, allows the user to map custom keys to custom values, based on submission or other data.

Example

The following example shows how you can allow the user to define a number of custom keys and map them to custom values, which in this case is limited to twenty. We are also excluding the creditcard field from the drop downs which contain the form fields as choices.

array(
    'title'  => esc_html__( 'This is the title for Section 1', 'sometextdomain' ),
    'fields' => array(
        array(
            'name'      => 'metaData',
            'type'      => 'generic_map',
            'label'     => esc_html__( 'Example', 'sometextdomain' ),
            'key_field' => array(
                'title' => 'Key Field',
                'type'  => 'text',
            ),
            'value_field' => array(
                'title' => 'Value Field',
                'text'  => 'text',
            ),
            'validation_callback' => array( $this, 'validate_custom_meta' ),
        ),
    ),
),

Validation

In the above example a validation callback is also specified to ensure that the limit is not exceeded and that the custom keys don’t exceed the character limit defined by the third-party service.

public function validate_custom_meta( $field ) {
	//Number of keys is limited to 20 - interface should control this, validating just in case
	//key names can only be max of 40 characters

	$settings = $this->get_posted_settings();
	$metaData = $settings['metaData'];

	if ( empty( $metaData ) ) {
		return;
	}

	//check the number of items in metadata array
	$metaCount = count( $metaData );
	if ( $metaCount > 20 ) {
		$this->set_field_error( array( esc_html__( 'You may only have 20 custom keys.' ), 'sometextdomain' ) );

		return;
	}

	//loop through metaData and check the key name length (custom_key)
	foreach ( $metaData as $meta ) {
		if ( empty( $meta['custom_key'] ) && ! empty( $meta['value'] ) ) {
			$this->set_field_error( array( 'name' => 'metaData' ), esc_html__( "A field has been mapped to a custom key without a name. Please enter a name for the custom key, remove the metadata item, or return the corresponding drop down to 'Select a Field'.", 'sometextdomain' ) );
			break;
		} elseif ( strlen( $meta['custom_key'] ) > 40 ) {
			$this->set_field_error( array( 'name' => 'metaData' ), sprintf( esc_html__( 'The name of custom key %s is too long. Please shorten this to 40 characters or less.', 'sometextdomain' ), $meta['custom_key'] ) );
			break;
		}
	}
}

Helpers

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

get_generic_map_fields()

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

$metaData = $this->get_generic_map_fields( $feed, 'metaData' );
  • $feed Feed Object

    Feed object or settings array.

  • $field_name string

    The name property of the generic_map field to retrieve the mapped fields for.

  • $form array

    Form object. Defaults to empty array.

  • $entry array

    Entry object. Defaults to empty array.

Uses

  • settings_generic_map