Introduction
The Field object contains all settings for a particular field. It is part of the Form Object and is available in most Gravity Forms hooks. It can be manipulated to dynamically change the way the field is displayed.
Usage
// returns the label of the first field on the form
$form['fields'][0]->label;
// displays the types of every field in the form
foreach ( $form['fields'] as $field ) {
echo $field->type . '<br/>';
}
Properties
Basic Properties
Property | Type | Description |
---|---|---|
adminLabel | string | When specified, the value of this property will be used on the admin pages instead of the label. It is useful for fields with long labels. Applies to: All fields |
adminOnly | bool | Determines if this field should only visible on the administration pages. A value of 1 will mark the field as admin only and will hide it from the public form. Useful for fields such as “status” that help with managing entries, but don’t apply to users filling out the form. Applies to: All fields |
allowsPrepopulate | bool | Determines if the field’s value can be pre-populated dynamically. 1 to allow field to be pre-populated, 0 otherwise. Applies to: All fields |
choices | array | Contains the available choices for the field. For instance, drop down items and checkbox items are configured with this property. Applies to: select, checkbox, radio, post_category. See Note 1. |
Conditional Logic | array | Controls the visibility of the field based on values selected by the user. |
content | string | Content of an HTML block field to be displayed on the form Applies to: html |
cssClass | string | Custom CSS class to be added to the <li> tag that contains the field. Useful to apply custom formatting to specific fields. Applies to: All fields |
defaultValue | string | Contains the default value for the field. When specified, the field’s value will be populated with the contents of this property when the form is displayed. Applies to: hidden, text, website, phone, number, date, textarea, email, post_title, post_content, post_excerpt, post_tags, post_custom_field |
description | string | Field description. Applies to: All fields |
enableChoiceValue | bool | Determines if the field (checkbox, select or radio) have choice values enabled, which allows the field to have choice values different from the labels that are displayed to the user Applies to: checkbox, select and radio |
errorMessage | string | Contains the message that is displayed for fields that fail validation Applies to: All fields except html, section and hidden |
id | integer | Field id |
inputName | string | Assigns a name to this field so that it can be populated dynamically via this input name. Only applicable when allowsPrepopulate is set to 1. Applies to: All fields except section and captcha |
isRequired | bool | Determines if the field requires the user to enter a value. 1 marks the field as required, 0 marks the field as not required. Fields marked as required will prevent the form from being submitted if the user has not entered a value in it. Applies to: All fields except section, html and captcha |
label | string | Field label that will be displayed on the form and on the admin pages Applies to: All fields |
noDuplicates | bool | Determines if the field allows duplicate submissions. 1 to prevent users from submitting the same value more than once, 0 to allow duplicate values. Applies to: hidden, text, website, phone, number, date, time, textarea, select, radio, email, post_custom_field |
size | string | Determines the size of the field when displayed on the page Applies to: All fields except html, section and captcha Possible values: small, medium, large |
type | string | The type of field to be displayed Applies to: All fields Possible values: html, hidden, section, text, website, phone, number, date, time, textarea, select, checkbox, radio, name, address, fileupload, email, post_title, post_content, post_excerpt, post_tags, post_category, post_image, post_custom_field, captcha |
placeholder | string | Use the Placeholder to give a hint at the expected value or format. Applies to: All fields except section, HTML, captcha, hidden, radio buttons, checkbox, multiple choice, image choice, page |
choiceAlignment | string | The alignment for choices Applies to: multiple choice field Possible values: horizontal, vertical |
Note 1
$choices = $field->choices;
$choices[0]['text'] = 'Drop down item 1';
$field->choices = $choices;
- Each choice in the array has the following Properties:
- text string The text to be displayed to the user when displaying this choice.
- value string The value to be stored in the database when this choice is selected. Note: This property is only supported by the Drop Down and Post Category fields. Checkboxes and Radio fields will store the text property in the database regardless of the value property
- isSelected bool Determines if this choice should be selected by default when displayed. The value 1 will select the choice, 0 will display it unselected.
Post Fields
Property | Type | Description |
---|---|---|
postCustomFieldName | string | The name of the Post Custom Field that the submitted value should be assigned to. Applies to: post_custom_field |
displayAllCategories | bool | Determines if all categories should be displayed on the Post Category drop down. 1 to display all categories, 0 otherwise. If this property is set to 1 (display all categories), the Post Category drop down will display the categories hierarchically. Applies to: post_category |
displayCaption | bool | Controls the visibility of the caption metadata for Post Image fields. 1 will display the caption field, 0 will hide it. Applies to: post_image |
displayDescription | bool | Controls the visibility of the description metadata for Post Image fields. 1 will display the description field, 0 will hide it. Applies to: post_image |
displayTitle | bool | Controls the visibility of the title metadata for Post Image fields. 1 will display the title field, 0 will hide it. Applies to: post_image |
inputType | string | Contains a field type and allows a field type to be displayed as another field type. A good example is the Post Custom Field, that can be displayed as various different types of fields. Applies to: post_custom_field |
Advanced Fields
Number
Property | Type | Description |
---|---|---|
numberFormat | string | Specifies the format allowed for the number field. Applies to: number Possible values: decimal_dot, decimal_comma decimal_dot: 9,999.99 decimal_comma: 9.999,99 |
rangeMin | float | Minimum allowed value for a number field. Values lower than the number specified by this property will cause the field to fail validation. Applies to: number |
rangeMax | float | Maximum allowed value for a number field. Values higher than the number specified by this property will cause the field to fail validation. Applies to: number |
Date
Property | Type | Description |
---|---|---|
calendarIconType | string | Determines how the date field displays it’s calendar icon Applies to: date Possible values: calendar, custom, none calendar: Displays the standard calendar icon shipped with Gravity Forms custom: Allows administrators to specify a custom icon none: Disables the calendar icon |
calendarIconUrl | float | Contains the URL to the custom calendar icon. Only applicable when calendarIconType is set to custom Applies to: date |
dateFormat | string | Determines how the date is displayed Applies to: date Possible values: mdy, dmy mdy: 01/25/2010 dmy: 25/01/2010 |
Phone
Property | Type | Description |
---|---|---|
phoneFormat | string | Determines the allowed format for phones. If the phone value does not conform with the specified format, the field will fail validation. Applies to: phone Possible values: standard, international standard: Phone must be in the format: “(###)### – ####” international: Phone can be in any format |
Name and Address
Property | Type | Description |
---|---|---|
nameFormat | string | Determines the format of the name field Applies to: name Possible values: normal, extended, simple normal: Displays first and last name fields extended: Displays prefix, first, last and suffix fields simple: Displays one name field |
addressType | string | Determines the type of address to be displayed. Applies to: address Possible values: international, us, canadian international: State input is displayed as a text field and the country drop down is displayed |
defaultCountry | string | Contains the country that will be selected by default. Only applicable when addressType is set to international Applies to: address |
defaultProvince | string | Contains the province that will be selected by default. Only applicable when addressType is set to canadian Applies to: address |
defaultState | string | Contains the state that will be selected by default. Only applicable when addressType is set to us Applies to: address |
hideAddress2 | bool | Controls the visibility of the address 2 field. A value of 1 will hide the address 2 field, 0 will display it. Applies to: address |
hideCountry | bool | Controls the visibility of the country drop down. A value of 1 will hide the country drop down, 0 will display it. Only applicable when addressType is set to international Applies to: address |
hideState | bool | Controls the visibility of the state field. A value of 1 will hide the state field, 0 will display it. Applies to: address |
inputs | array | For fields with multiple inputs (i.e. Name, Address), this property contains a list of inputs. This property also applies to the checkbox field as checkboxes are treated as multi-input fields (since each checkbox item is stored separately). Applies to: name, address, checkbox. See Note 2. |
Note 2
$inputs = $field->inputs;
$inputs[0]['label'] = 'First Name';
//sets the label for the first input
$field->inputs = $inputs
- Each input has the following properties.
- id float The input id. Input Ids follow the following naming convention: “FIELDID.INPUTID” (i.e. 5.1), where FIELDID is the id of the containing field and INPUTID specifies the input field. For example, inputs for the name field are numbered as follows:
- FIELDID.2 Name Prefix input id (i.e. 4.2)
- FIELDID.3 First Name input id (i.e. 4.3)
- FIELDID.6 Last Name input id (i.e. 4.6)
- FIELDID.8 Name Suffix input id (i.e. 4.8)
- label string Input label
- name string When the field is configured with allowsPrepopulate set to 1, this property contains the parameter name to be used to populate this field (equivalent to the inputName property of single-input fields)
- id float The input id. Input Ids follow the following naming convention: “FIELDID.INPUTID” (i.e. 5.1), where FIELDID is the id of the containing field and INPUTID specifies the input field. For example, inputs for the name field are numbered as follows:
File Upload
Property | Type | Description |
---|---|---|
allowedExtensions | string | Contains a comma delimited list of file extensions that are allowed to be uploaded. (i.e. jpg,gif,png) Applies to: fileupload, post_image |
CAPTCHA
Property | Type | Description |
---|---|---|
captchaType | string | Determines the type of CAPTCHA field to be used Possible values: recaptcha, simple_captcha, math NOTE: simple_captcha and math CAPTCHA fields are only available when the “Really Simple CAPTCHA” plugin is installed |
captchaTheme | string | Determines the theme to be used for the reCAPTCHA field. Only applicable to the recaptcha captcha type. Possible values: red, white, blackglass, clean |
simpleCaptchaSize | string | Determines the CAPTCHA image size. Only applicable to simple_captcha and math captcha types. Possible values: small, medium, large |
simpleCaptchaFontColor | string | Determines the image’s font color, in HEX format (i.e. #CCCCCC). Only applicable to simple_captcha and math captcha types. |
simpleCaptchaBackgroundColor | string | Determines the image’s background color, in HEX format (i.e. #CCCCCC). Only applicable to simple_captcha and math captcha types. |
Other
Property | Type | Description |
---|---|---|
enablePasswordInput | bool | Determines if a text field input tag should be created with a ‘password’ type Applies to: text |
maxLength | integer | Specifies the maximum number of characters allowed in a text or paragraph field. |
enableEnhancedUI | bool | When set to true, the Chosen jQuery script will be applied to this field, enabling search capabilities to Drop Down fields and a more user-friendly interface for Multi Select fields. Applies to: select, multiselect |
Pricing Fields
Property | Type | Description |
---|---|---|
basePrice | float | Base price for a single product field. Applies to: singleproduct |
disableQuantity | bool | Specifies if the quantity field on single product fields should be displayed or hidden. Applies to: singleproduct |
productField | integer | Available only on Option fields. Specifies which product field the current option field is linked to. Applies to: option |
enablePrice | bool | Specifies if a price can be entered for each field choice. This option is automatically turned ON for pricing fields when using Drop Down, Radio Button or Checkbox input types. Applies to: checkbox, select, radio |
Add-On Fields
See the following pages for details about fields added by add-ons:
Field JSON
This example shows how a field object would look when formatted as JSON for use by the Gravity Forms CLI Add-On.
{
"type": "select",
"label": "My Dropdown",
"choices": [{
"text": "Choice 1",
"value": "one"
}, {
"text": "Choice 2",
"value": "two"
}],
"id": "2",
"visibility": "visible",
"formId": "14",
"pageNumber": 1,
"isRequired": false
}