GF_Field_AddressIntroductionSettings and PropertiesSettingsProperties$entry ValueUseful Methodsget_address_types()get_countries()get_country_code()get_country_codes()get_us_states()get_us_state_code()get_canadian_provinces()get_value_export()HooksSource Code
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:
12345//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.
123456789101112131415161718192021222324252627282930313233343536373839404142434445$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:
1234567$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
1$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:
123456789101112131415161718192021$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
1$countries = $field->get_countries();
Returns array
An array of country names in the following format:
1234567$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
1$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
1$country_codes = $field->get_country_codes();
Returns array
An array of the country name and its country code in the following format:
1234567$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
1$states = $field->get_us_states();
Returns array
An array of the US state names in the following format:
1234567$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
1$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
1$provinces = $field->get_canadian_provinces();
Returns array
An array of the Canadian provinces in the following format:
1234567$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
123456// 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:
gform_address_display_format
gform_address_street
gform_address_street2
gform_address_zip
gform_address_city
gform_address_state
gform_address_country
gform_default_address_type
gform_address_types
gform_countries
gform_us_states
gform_disable_address_map_link
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.
