Helper FunctionsIntroductionadd_field_before()add_field_before() Exampleadd_field_after()add_field_after() Exampleremove_field()remove_field() Examplereplace_field()replace_field() Example 1 – Adding Donation to Transaction Type Drop Downreplace_field() Example 2 – Adding First and Last Name to Billing Information for Mappingget_field()get_field() Examplesettings_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 );
$name string
The name property of the field these fields should be inserted before.
$fields array
An array of fields to be inserted.
$settings array
The 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' => '
' . __( 'PayPal Email Address', 'gravityformspaypal' ) . '
' . __( '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' => '
' . __( 'Mode', 'gravityformspaypal' ) . '
' . __( '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 );
$name string
The name property of the field these fields should be inserted after.
$fields array
An array of fields to be inserted.
$settings array
The 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() {
$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' => '
' . __( 'PayPal Email Address', 'gravityformspaypal' ) . '
' . __( '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' => '
' . __( 'Mode', 'gravityformspaypal' ) . '
' . __( '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 );
$name string
The name property of the field to be removed.
$settings array
The 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 );
$name string
The name property of the field to be replaced.
$fields array
An array of fields to be inserted.
$settings array
The 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 ) {
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 );
$name string
The name property of the field to be retrieved.
$settings array
The 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 ) {}
$field array
The array containing the field properties.
$echo boolean
Default 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 ) {}
$field array
The array containing the field properties.
$echo boolean
Default 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 ) {}
$field array
The array containing the field properties.
$echo boolean
Default 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 ) {}
$field array
The array containing the field properties.
$echo boolean
Default 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() ) {}
$choices array
The 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() ) {}
$choice array
The choice properties.
$field_attributes array
The fields attributes.
$default_choice_attributes array
The 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 ) {}
$field array
The array containing the field properties.
$echo boolean
Default 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='' ) {}
$choice array
The array containing the choice properties.
$horizontal_class string
The CSS class to style the checkbox items horizontally.
$attributes string
The attributes to be added to the input element.
$value string
Indicates if the current choice is selected (1 if field has been checked. 0 or null otherwise).
$tooltip string
The 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 ) {}
$choice array
The array containing the choice properties.
$attributes string
The attributes to be added to the input element.
$value string
Indicates if the current choice is selected (1 if field has been checked. 0 or null otherwise).
$tooltip string
The 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 ) {}
$choice array
The array containing the choice properties.
$attributes string
The attributes to be added to the input element.
$value string
Indicates if the current choice is selected (1 if field has been checked. 0 or null otherwise).
$tooltip string
The 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 ) {}
$field array
The array containing the field properties.
$echo boolean
Default 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 ) {}
$choices array
The array containing the field choices.
$selected_value string
The 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 ) {}
$choice array
The array containing the choice properties.
$selected_value string
The 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 ) {}
$field array
The array containing the field properties.
$echo boolean
Default 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 ) {}
$field array
The array containing the parent fields properties.
$echo boolean
Default 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 ) {}
$parent_field array
The array containing the parent fields properties.
$field_name string
The 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 ) {}
$field array
The array containing the child field properties.
$form_id integer
The 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 ) {}
$form_id integer
The ID of the current form.
$field_type string|array
The type of fields to be included.
$exclude_field_types string|array
The 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 ) {}
$field array
The array containing the field properties.
$echo boolean
Default 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() ) {}
$form Form Object
The current form.
$args array
Additional 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 ) {}
$field array
The array containing the field properties.
$echo boolean
Default 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 ) {}
$field array
The array containing the parent fields properties.
$echo boolean
Default 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 ) {}
$field array
The array containing the parent fields properties.
$echo boolean
Default is true. Indicates whether the field markup should be echoed to the page.
