List of Settings API Helper Functions

• Introduction
• add_field_before()
• add_field_before() Example
• add_field_after()
• add_field_after() Example
• remove_field()
• remove_field() Example
• replace_field()
• replace_field() Example 1 - Adding Donation to Transaction Type Drop Down
• replace_field() Example 2 - Adding First and Last Name to Billing Information for Mapping
• get_field()
• get_field() Example
• settings_text()
• settings_textarea()
• settings_hidden()
• settings_radio()
• choices_have_icon()
• get_choice_attributes()
• settings_checkbox()
• checkbox_item()
• checkbox_input()
• checkbox_input_{$choice_name}()
• settings_select()
• get_select_options()
• get_select_option()
• settings_select_custom()
• settings_field_map()
• field_map_table_header()
• field_map_title()
• get_mapped_field_name()
• settings_field_map_select()
• get_field_map_choices()
• settings_field_select()
• get_form_fields_as_choices()
• settings_checkbox_and_select()
• settings_dynamic_field_map()
• settings_save()

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 );

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 );

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() {
$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_after( 'feedName', $fields, $default_settings );
return $default_settings;
}

The code above produces output similar to the following:

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 );

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 );

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 ) {
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 );

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 ) {}

settings_textarea()

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

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

settings_hidden()

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

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

settings_radio()

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

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

choices_have_icon()

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

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

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() ) {}

settings_checkbox()

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

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

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='' ) {}

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 ) {}

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 ) {}

settings_select()

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

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

get_select_options()

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

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

get_select_option()

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

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

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 ) {}

settings_field_map()

Returns the field markup.

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

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 ) {}

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 ) {}

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 ) {}

settings_field_select()

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

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

get_form_fields_as_choices()

Retrieve an array of choices containing the form fields.

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

settings_checkbox_and_select()

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

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

settings_dynamic_field_map()

Returns the field markup for the dynamic_field_map type field.

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

settings_save()

Returns the markup for the save button.

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