List of Settings API Helper Functions

Introduction

These helper functions may be used to remove, modify, and add fields when working with the Settings API

add_field_before()

$this->add_field_before( $name, $fields, $settings );

Parameters

ParameterTypeDescription
$namestringThe name property of the field these fields should be inserted before.
$fieldsarrayAn array of fields to be inserted.
$settingsarrayThe array of sections containing their current fields.

add_field_before() Example

This example uses the same code as the add field after example, with the only change being calling the add_field_before function and specifying the field to place it before as transactionType. This results in the same placement on the page as the other example.

public function feed_settings_fields() {
    $default_settings = parent::feed_settings_fields();

    //--add PayPal Email Address field
    $fields = array(
        array(
            'name'     => 'paypalEmail',
            'label'    => __( 'PayPal Email Address ', 'gravityformspaypal' ),
            'type'     => 'text',
            'class'    => 'medium',
            'required' => true,
            'tooltip'  => '<h6>' . __( 'PayPal Email Address', 'gravityformspaypal' ) . '</h6>' . __( 'Enter the PayPal email address where payment should be received.', 'gravityformspaypal' )
        ),
        array(
            'name'          => 'mode',
            'label'         => __( 'Mode', 'gravityformspaypal' ),
            'type'          => 'radio',
            'choices'       => array(
                array( 'id' => 'gf_paypal_mode_production', 'label' => __( 'Production', 'gravityformspaypal' ), 'value' => 'production' ),
                array( 'id' => 'gf_paypal_mode_test', 'label' => __( 'Test', 'gravityformspaypal' ), 'value' => 'test' ),
            ),
            'horizontal'    => true,
            'default_value' => 'production',
            'tooltip'       => '<h6>' . __( 'Mode', 'gravityformspaypal' ) . '</h6>' . __( 'Select Production to receive live payments. Select Test for testing purposes when using the PayPal development sandbox.', 'gravityformspaypal' )
        ),
    );

    $default_settings = $this->add_field_before( 'transactionType', $fields, $default_settings );
    return $default_settings;
}

add_field_after()

$this->add_field_after( $name, $fields, $settings );

Parameters

ParameterTypeDescription
$namestringThe name property of the field these fields should be inserted after.
$fieldsarrayAn array of fields to be inserted.
$settingsarrayThe array of sections containing their current fields.

add_field_after() Example

This example creates two new fields, PayPal Email Address and Mode, and places them right after the Feed Name field.

public function feed_settings_fields() {
		return array(
			array(
				'title'       => esc_html__('Feed Settings', 'simpleaddon'),
				'description' => esc_html__('Configure the feed settings below', 'simpleaddon'),
				'fields'      => array(
					array(
						'type'     => 'text',
						'name'     => 'feedName',
						'label'    => esc_html__('Feed Name', 'simpleaddon'),
						'required' => true,
						'class'    => 'medium'
					),
					array(
						'type'     => 'select',
						'name'     => 'feedAction',
						'label'    => esc_html__('Action', 'simpleaddon'),
						'required' => true,
						'choices'  => array(
							array(
								'label' => esc_html__('First Action', 'simpleaddon'),
								'value' => 'first'
							),
							array(
								'label' => esc_html__('Second Action', 'simpleaddon'),
								'value' => 'second'
							)
						)
					),
					array(
						'type'       => 'field_select',
						'name'       => 'mappedField',
						'label'      => esc_html__('Map to Field', 'simpleaddon'),
						'tooltip'    => esc_html__('Select which field to map', 'simpleaddon'),
						'required'   => true
					)
				)
			)
		);
	}

The code above produces output similar to the following:

Image showing add-on settings

remove_field()

When extending the GFPaymentAddOn you may want to remove some of the default fields from your add-ons feed configuration page.

$this->remove_field( $name, $settings );

Parameters

ParameterTypeDescription
$namestringThe name property of the field to be removed.
$settingsarrayThe array of sections containing their current fields.

remove_field() Example

This example removes the Setup Fee field.

public function feed_settings_fields() {
    $default_settings = parent::feed_settings_fields();

    // Hide default display of setup fee
    $default_settings = $this->remove_field( 'setupFee', $default_settings );

    return $default_settings;
}

replace_field()

Instead of removing a field, you may replace it with a modified version. When using replace_field, you do not need to worry about the placement on the page because the field will remain in the same location.

$this->replace_field( $name, $fields, $settings );

Parameters

ParameterTypeDescription
$namestringThe name property of the field to be replaced.
$fieldsarrayAn array of fields to be inserted.
$settingsarrayThe array of sections containing their current fields.

replace_field() Example 1 – Adding Donation to Transaction Type Drop Down

This example adds Donation as a choice in the Transaction Type drop down by replacing the transaction type field with an altered version of it. You could also achieve this by removing the field and adding a new version of it and placing it in the correct location on the page.

public function feed_settings_fields() {
    $default_settings = parent::feed_settings_fields();

    //--add donation to transaction type drop down
    $transaction_type = $this->get_field( 'transactionType', $default_settings );
    $choices          = $transaction_type['choices'];
    $add_donation     = true;

    foreach ( $choices as $choice ) {
        //add donation option if it does not already exist
        if ( $choice['value'] == 'donation' ) {
            $add_donation = false;
        }
    }

    if ( $add_donation ) {
        //add donation transaction type
        $choices[] = array( 'label' => __( 'Donations', 'gravityformspaypal' ), 'value' => 'donation' );
    }

    $transaction_type['choices'] = $choices;
    $default_settings             = $this->replace_field( 'transactionType', $transaction_type, $default_settings );

    return $default_settings;
}

replace_field() Example 2 – Adding First and Last Name to Billing Information for Mapping

public function feed_settings_fields() {
    $default_settings = parent::feed_settings_fields();

    //--get billing info section and add customer first/last name
    $billing_info   = $this->get_field( 'billingInformation', $default_settings );
    $billing_fields = $billing_info['field_map'];
    $add_first_name = true;
    $add_last_name  = true;

    foreach ( $billing_fields as $mapping ) {
        //add first/last name if it does not already exist in billing fields
        if ( $mapping['name'] == 'firstName' ) {
            $add_first_name = false;
        } else if ( $mapping['name'] == 'lastName' ) {
            $add_last_name = false;
        }
    }

    if ( $add_last_name ) {
        //add last name
        array_unshift( $billing_info['field_map'], array( 'name' => 'lastName', 'label' => __( 'Last Name', 'gravityformspaypal' ), 'required' => false ) );
    }
    if ( $add_first_name ) {
        //add first name
        array_unshift( $billing_info['field_map'], array( 'name' => 'firstName', 'label' => __( 'First Name', 'gravityformspaypal' ), 'required' => false ) );
    }

    $default_settings = $this->replace_field( 'billingInformation', $billing_info, $default_settings );

    return $default_settings;
}

get_field()

$this->get_field( $name, $settings );

Parameters

ParameterTypeDescription
$namestringThe name property of the field to be retrieved.
$settingsarrayThe array of sections containing the current fields.

get_field() Example

See the replace_field() examples above.

settings_text()

Renders and initializes a text input based on the $field array.

protected function settings_text( $field, $echo = true ) {}

Parameters

ParameterTypeDescription
$fieldarrayThe array containing the field properties.
$echobooleanDefault is true. Indicates whether the field markup should be echoed to the page.

settings_textarea()

Renders and initializes a textarea element based on the $field array.

protected function settings_textarea( $field, $echo = true ) {}

Parameters

ParameterTypeDescription
$fieldarrayThe array containing the field properties.
$echobooleanDefault is true. Indicates whether the field markup should be echoed to the page.

settings_hidden()

Renders and initializes a hidden input based on the $field array.

protected function settings_hidden( $field, $echo = true ) {}

Parameters

ParameterTypeDescription
$fieldarrayThe array containing the field properties.
$echobooleanDefault is true. Indicates whether the field markup should be echoed to the page.

settings_radio()

Renders and initializes one or more radio type inputs based on the $field array.

protected function settings_radio( $field, $echo = true ) {}

Parameters

ParameterTypeDescription
$fieldarrayThe array containing the field properties.
$echobooleanDefault is true. Indicates whether the field markup should be echoed to the page.

choices_have_icon()

Determines if any of the choices for this field have an icon.

public function choices_have_icon( $choices = array() ) {}

Parameters

ParameterTypeDescription
$choicesarrayThe array containing the field choices.

get_choice_attributes()

Parses the properties of the $choice array and returns a new array containing a set of HTML attributes to be added to the HTML element.

protected function get_choice_attributes( $choice, $field_attributes, $default_choice_attributes = array() ) {}

Parameters

ParameterTypeDescription
$choicearrayThe choice properties.
$field_attributesarrayThe field’s attributes.
$default_choice_attributesarrayThe choices default attributes. Default is an empty array.

settings_checkbox()

Renders and initializes one or more checkbox type inputs based on the $field array.

protected function settings_checkbox( $field, $echo = true ) {}

Parameters

ParameterTypeDescription
$fieldarrayThe array containing the field properties.
$echobooleanDefault is true. Indicates whether the field markup should be echoed to the page.

checkbox_item()

Returns the markup for an individual checkbox item for the given choice array.

protected function checkbox_item( $choice, $horizontal_class, $attributes, $value, $tooltip, $error_icon='' ) {}

Parameters

ParameterTypeDescription
$choicearrayThe array containing the choice properties.
$horizontal_classstringThe CSS class to style the checkbox items horizontally.
$attributesstringThe attributes to be added to the input element.
$valuestringIndicates if the current choice is selected (1 if field has been checked, 0 or null otherwise).
$tooltipstringThe tooltip for this choice.

checkbox_input()

Returns the markup for an individual checkbox input and label for the given choice array.

protected function checkbox_input( $choice, $attributes, $value, $tooltip ) {}

Parameters

ParameterTypeDescription
$choicearrayThe array containing the choice properties.
$attributesstringThe attributes to be added to the input element.
$valuestringIndicates if the current choice is selected (1 if field has been checked. 0 or null otherwise).
$tooltipstringThe tooltip for this choice.

checkbox_input_{$choice_name}()

Define a custom checkbox_input_ function ending with a specific choice name to return a custom checkbox input and label markup for that choice.

public function checkbox_input_{$choice_name}( $choice, $attributes, $value, $tooltip ) {}

Parameters

ParameterTypeDescription
$choicearrayThe array containing the choice properties.
$attributesstringThe attributes to be added to the input element.
$valuestringIndicates if the current choice is selected (1 if field has been checked. 0 or null otherwise).
$tooltipstringThe tooltip for this choice.

settings_select()

Renders and initializes a drop down field based on the $field array.

protected function settings_select( $field, $echo = true ) {}

Parameters

ParameterTypeDescription
$fieldarrayThe array containing the field properties.
$echobooleanDefault is true. Indicates whether the field markup should be echoed to the page.

get_select_options()

Prepares an HTML string of options for a drop down field.

public function get_select_options( $choices, $selected_value ) {}

Parameters

ParameterTypeDescription
$choicesarrayThe array containing the field choices.
$selected_valuestringThe value currently selected for the field.

get_select_option()

Prepares an HTML string for a single drop down field option.

public function get_select_option( $choice, $selected_value ) {}

Parameters

ParameterTypeDescription
$choicearrayThe array containing the choice properties.
$selected_valuestringThe value currently selected for the field.

settings_select_custom()

Renders and initializes a drop down field with a input field for custom input based on the $field array.

protected function settings_select_custom( $field, $echo = true ) {}

Parameters

ParameterTypeDescription
$fieldarrayThe array containing the field properties.
$echobooleanDefault is true. Indicates whether the field markup should be echoed to the page.

settings_field_map()

Returns the field markup.

public function settings_field_map( $field, $echo = true ) {}

Parameters

ParameterTypeDescription
$fieldarrayThe array containing the parent field’s properties.
$echobooleanDefault is true. Indicates whether the field markup should be echoed to the page.

field_map_table_header()

Returns the thead element with the column headers.

public function field_map_table_header() {}

field_map_title()

Returns the title to be displayed in the left column of the table, the column containing the labels of the child fields. Defaults to Field; override this function to return a custom title.

protected function field_map_title() {}

get_mapped_field_name()

Returns the key for this field as used in the meta property of the Feed Object. e.g. contactStandardFields_first_name

public function get_mapped_field_name( $parent_field, $field_name ) {}

Parameters

ParameterTypeDescription
$parent_fieldarrayThe array containing the parent fields properties.
$field_namestringThe name property of the field_map child field.

settings_field_map_select()

Returns the markup for the drop down containing the form fields and entry meta choices.

public function settings_field_map_select( $field, $form_id ) {}

Parameters

ParameterTypeDescription
$fieldarrayThe array containing the child field properties.
$form_idintegerThe ID of the current form.

get_field_map_choices()

Returns an array of form field and entry meta choices.

public static function get_field_map_choices( $form_id, $field_type = null, $exclude_field_types = null ) {}

Parameters

ParameterTypeDescription
$form_idintegerThe ID of the current form.
$field_typestring | arrayThe type of fields to be included.
$exclude_field_typesstring | arrayThe type of fields to be excluded.

settings_field_select()

Renders a drop down field containing the form fields as choices.

protected function settings_field_select( $field, $echo = true ) {}

Parameters

ParameterTypeDescription
$fieldarrayThe array containing the field properties.
$echobooleanDefault is true. Indicates whether the field markup should be echoed to the page.

get_form_fields_as_choices()

Retrieve an array of choices containing the form fields.

public function get_form_fields_as_choices( $form, $args = array() ) {}

Parameters

ParameterTypeDescription
$formForm ObjectThe current form.
$argsarrayAdditional settings to check for (field and input types to include, callback for applicable input type).

settings_checkbox_and_select()

Renders and initializes a checkbox field that displays a select field when checked.

protected function settings_select( $field, $echo = true ) {}

Parameters

ParameterTypeDescription
$fieldarrayThe array containing the field properties.
$echobooleanDefault is true. Indicates whether the field markup should be echoed to the page.

settings_dynamic_field_map()

Returns the field markup for the dynamic_field_map type field.

public function settings_dynamic_field_map( $field, $echo = true ) {}

Parameters

ParameterTypeDescription
$fieldarrayThe array containing the parent field’s properties.
$echobooleanDefault is true. Indicates whether the field markup should be echoed to the page.

settings_save()

Returns the markup for the save button.

public function settings_save( $field, $echo = true ) {}

Parameters

ParameterTypeDescription
$fieldarrayThe array containing the parent field’s properties.
$echobooleanDefault is true. Indicates whether the field markup should be echoed to the page.