GF_Field_Address

Introduction

The GF_Field_Address class extends the GF_Field class, also known as the Field Object. This class is responsible for determining how the Address field is rendered when the form is displayed and how its value is handled during and after form submission.

Settings and Properties

Settings control what options are available to the admin user when configuring the field in the form editor. Gravity Forms includes many built-in settings such as Field Label, Field Description, Choices, Conditional Logic, etc. In addition to built-in settings, custom settings can also be developed. For more information on how to develop custom settings and how to associate settings to a field, visit the GF_Field page.

Properties contain the values specified by the settings and generally are part of the Field Object.

The properties may be retrieved by accessing the Field Object as follows:

//get the field
$field = GFFormsModel::get_field( $form, 1 );

//get the address type
$address_type = $field->addressType;

Settings

The following settings are available for the field:

  • address_setting
    Controls whether the group of Address field settings display. This group includes the “Address Type”, custom sub-labels, ability to show/hide the individual field parts, “Default Country” (if International type is chosen), “Default State” (if United States is chosen), “Default Province” (if Canadian is chosen).

  • admin_label_setting
    Controls whether the “Admin Field Label” setting appears.

  • conditional_logic_field_setting
    Controls whether the “Enable Conditional Logic” setting appears.

  • copy_values_option
    Controls whether the “Display option to use the values submitted in different field” setting displays. The option is used to determine whether the values from another address field on the form may be used for the current field. Example: Copying Billing Address to the Mailing Address field.

  • css_class_setting
    Controls whether the “Custom CSS Class” setting displays. This allows a custom css to be used for the field.

  • default_input_values_setting
    For complex fields like the name, time, address fields, this controls whether the “Default Values” section will appear which lets you set values for the individual components of the field. When it is not a complex field, the “default_value_setting” controls the display of this section.

  • description_setting
    Controls whether the “Description” setting appears. This allows a description for the field to be displayed.

  • error_message_setting
    Controls whether the “Custom Validation Message” setting which allows a custom message to be used appears.

  • input_placeholders_setting
    For complex fields like the name, time, and address fields, this controls whether the “Placeholders” section will appear which lets you set placeholder text for the individual components of the field. When it is not a complex field, the “placeholder_setting” controls the display of this section.

  • label_setting
    Controls whether the “Field Label” setting which allows the label to be changed appears.

  • prepopulate_field_setting
    Controls whether the “Allow field to be populated dynamically” setting appears.

  • rules_setting
    Controls whether the “Rules” settings section displays. The “Required” option shows when this is active.

  • sub_label_placement_setting
    If a field has sub-labels, controls whether the “Sub-Label Placement” setting appears.

  • visibility_setting
    Controls whether the “Visibility” setting displays. The controls whether the option of visibility being for “Everyone” or “Admin Only” can be set.

Properties

Below is a listing of the properties inherited from the parent class, and the properties unique to the field:

  • addressType string

    The address type. This indicates the information/layout of the address. The available choices are “international”, “canadian”, and “us”.

  • adminLabel string

    The label to be used on admin pages instead of the label, useful for fields with long labels.

  • allowsPrepopulate boolean

    Determines if the field values can be dynamically populated. Default is false.

  • conditionalLogic array

    An associative array containing the conditional logic rules. See the Conditional Logic Object for more details.

  • copyValuesOptionDefault boolean

    Determines whether the option to copy values is turned on or off by default.

  • copyValuesOptionField integer

    The field id of the field being used as the copy source.

  • copyValuesOptionLabel string

    The label that appears next to the copy values option when the form is displayed. The default value is “Same as previous”.

  • defaultCountry string

    The default country to be chosen in the Country drop down, if displayed. If the “defaultValue” property is set in the “inputs” array for the country input, the defaultValue will be used instead of this property. This is a legacy property that should no longer be used. Instead, use the “defaultValue” property of the “inputs” array.

  • defaultProvince string

    The default province to be chosen in the Province drop down, if displayed. If the “defaultValue” property is set in the “inputs” array for the province input, the defaultValue will be used instead of this property. This is a legacy property that should no longer be used. Instead, use the “defaultValue” property of the “inputs” array.

  • defaultState string

    The default state to be chosen in the State drop down, if displayed. If the “defaultValue” property is set in the “inputs” array for the state input, the defaultValue will be used instead of this property. This is a legacy property that should no longer be used. Instead, use the “defaultValue” property of the “inputs” array.

  • description string

    The field description.

  • descriptionPlacement string

    The placement of the field description. The description may be placed “above” or “below” the field inputs. If the placement is not specified, then the description placement setting for the Form Layout is used.

  • enableCopyValuesOption boolean

    Indicates whether the copy values option can be used. This option allows users to skip filling out the field and use the same values as another. For example, if the mailing and billing address are the same.

  • errorMessage string

    The custom error message to be displayed if the field fails validation.

  • formId integer

    The form ID.

  • hideAddress2 boolean

    Legacy property used to control whether the address2 input is visible. To hide the state, use the “isHidden” property of the “inputs” array instead.

  • hideCountry boolean

    Legacy property used to control whether the country input is visible. To hide the state, use the “isHidden” property of the “inputs” array instead.

  • inputs array

    An array containing the the individual properties for each element of the address field.

    • id integer

      The id of the input field.

    • name string

      The name of the parameter used for the input when dynamically populating the field.

    • label string

      The label for the input.

    • customLabel string

      The custom label for the input. When set, this is used in place of the label.

    • placeholder string

      Placeholder text to give the user a hint on how to fill out the field. This is not submitted with the form.

    • defaultValue string

      The default value to be displayed/chosen in the input field.

    • isHidden boolean

      Controls whether the input is visible.

$inputs = array(
            array(
              'id'           => '1.1',
              'label'        => 'Street Address',
              'customLabel'  => 'Custom Street',
              'placeholder'  => 'Enter your street address',
              'defaultValue' => '100 Main Street',
              'isHidden'     => false
            ),
            array(
              'id'          => '1.2',
              'label'       => 'Address Line 2',
              'customLabel' => 'Custom Street 2',
              'placeholder' => 'Enter street 2',
              'isHidden'    => true

            ),
            array(
              'id'           => '1.3',
              'label'        => 'City',
              'customLabel'  => 'Custom City',
              'placeholder'  => 'Enter your city',
              'defaultValue' => 'Anywhere'
            ),
            array(
              'id'           => '1.4',
              'label'        => 'State / Province',
              'customLabel'  => 'Custom State',
              'placeholder'  => 'Enter your state',
              'defaultValue' => 'Virginia'
            ),
            array(
              'id'          => '1.5',
              'label'       => 'ZIP / Postal Code',
              'customLabel' => 'Custom Zip',
              'placeholder' => 'Enter your zip'
            ),
            array(
              'id'           => '1.6',
              'label'        => 'Country',
              'customLabel'  => 'Custom Country',
              'placeholder'  => 'Select your country',
              'defaultValue' => 'United States'
            ),
          )
  • hideState boolean

    Legacy property used to control whether the state input is visible. To hide the state, use the “isHidden” property of the “inputs” array instead.

  • id integer

    The field ID.

  • isRequired boolean

    Marking the field as required will prevent the form from being submitted if the user does not enter a value. Default is false.

  • label string

    The field label that will be displayed on the form and on the admin pages.

  • labelPlacement string

    The placement of the main field label “Address”. The choices are top-aligned (top_label), left-aligned (left_label), right-aligned (right_label). To control the sub-label placement of the fields within the address group, use the “subLabelPlacement” property.

  • subLabelPlacement string

    The placement of the labels for the fields (street, city, zip/postal code, etc.) within the address group. This setting controls all of the address pieces, they cannot be set individually. They may be aligned above or below the inputs. If this property is not set, the “Sub-Label Placement” setting on the Form Settings->Form Layout page is used. If no setting is specified, the default is above inputs.

  • type string

    The field type, which in this case is address.

$entry Value

The Address field is a multi-input field type with each input being saved separately in the Entry Object.

The key to each input value in the entry is the input id which is in the format {field_id}.{input_number}, so if the field ID is 5 here’s how you can access each input value:

$field_id      = 5;
$street_value  = rgar( $entry, $field_id . '.1' );
$street2_value = rgar( $entry, $field_id . '.2' );
$city_value    = rgar( $entry, $field_id . '.3' );
$state_value   = rgar( $entry, $field_id . '.4' );
$zip_value     = rgar( $entry, $field_id . '.5' );
$country_value = rgar( $entry, $field_id . '.6' );

The get_value_export method can also be used to retrieve the entry values.

Useful Methods

GF_Field_Address inherits it’s available methods from GF_Field and overrides a few of them where necessary to provide its required appearance and functionality. Here are a few methods which can be useful when writing custom code.

get_address_types()

The get_address_types() method returns an array of address types for the current form.

Usage Example

$address_types = $field->get_address_types( $form_id );
  • $form_id integer

    The form ID.

  • Returns array

    An array of the supported address types in the following format:

$address_types = array(
                   'international' => array(
                                        'label'	     => 'International',
                                        'zip_label'  => 'ZIP / Postal Code',
                                        'state_label => 'State / Province / Region'
                                      ),
                   'us'            => array(
                                        'label'       => 'United States',
                                        'zip_label'   => 'ZIP Code',
                                        'state_label' => 'State',
                                        'country'     => 'United States',
                                        'states'      => array( '', 'Alabama', 'Alaska', 'Arizona' )
                                      ),
                   'canadian'      => array(
                                        'label'       => 'Canadian',
                                        'zip_label'   => 'Postal Code',
                                        'state_label' => 'Province',
                                        'country'     => 'Canada',
                                        'states'      => array( '', 'Alberta', 'British Colombia', 'Manitoba' )
                                      )
                 );

get_countries()

The get_countries() method returns an array of countries.

Usage Example

$countries = $field->get_countries();
  • Returns array

    An array of country names in the following format:

$countries = array(
               'Afghanistan',
               'Albania',
               'Algeria',
               'American Samoa',
               'Zimbabwe'
             );

get_country_code()

The get_country_code() method return the two character code for the specified country.

Usage Example

$country_code = $field->get_country_code( $country_name );
  • $country_name string

    The country name.

  • Returns string

    The country code for the provided country name.

get_country_codes()

The get_country_codes() method returns an array of two character country codes.

Usage Example

$country_codes = $field->get_country_codes();
  • Returns array

    An array of the country name and its country code in the following format:

$country_codes = array(
                   'AFGHANISTAN'    => 'AF',
                   'ALBANIA'        => 'AL',
                   'ALGERIA'        => 'DZ',
                   'AMERICAN SAMOA' => 'AS',
                   'ZIMBABWE'       => 'ZW'
                 );

get_us_states()

The get_us_states() method returns an array of US state names.

Usage Example

$states = $field->get_us_states();
  • Returns array

    An array of the US state names in the following format:

$states = array(
            'Alabama',
            'Alaska',
            'Arizona',
            'Arkansas',
            'Wyoming'
          );

get_us_state_code()

The get_us_state_code() method returns the two character code for the specified state name.

Usage Example

$state = $field->get_us_state_code( $state_name );
  • $state_name string

    The state name.

  • Returns string

    The two character code for the provided state name.

get_canadian_provinces()

The get_canadian_provinces() method returns an array of Canadian provinces.

Usage Example

$provinces = $field->get_canadian_provinces();
  • Returns array

    An array of the Canadian provinces in the following format:

$provinces = array(
               'Alberta',
               'British Columbia',
               'Manitoba',
               'New Brunswick',
               'Yukon'
             );

get_value_export()

The get_value_export() method formats the entry value before it is used in entry exports and by framework add-ons that integrate with third-party services, however, you can use it in your custom code when interacting with the Form Object, Field Object and Entry Object.

Usage Examples

// if you have access to the $field object
$value = $field->get_value_export( $entry );

// if you don't have access to the $field object you can get that first like so
$field = GFFormsModel::get_field( $form, $field_id );
$value = $field->get_value_export( $entry, $input_id );
  • $entry Entry Object

    The entry from which the field value should be retrieved. Required.

  • $input_id string

    The ID of the field for which the value should be retrieved. Required when not using $field. Defaults to the $field->id property when not supplied. To access the value of a specific input you can include the input number with the field id e.g *5.1** would return the value from the Street Address input for field 5.

  • Returns string

    The values for the full field as a comma separated string or the value for a specific input.

Hooks

The following hooks are located in GF_Field_Address:

Source Code

The source code is located in includes/fields/class-gf-field-address.php in the Gravity Forms folder of your sites plugins directory.