bookmark_borderField Manipulation Helpers

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'  => '<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 );
  • $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'  => '<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:
Add Fields After Example

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.