Introduction
The form object, available to most action hooks and filters, is an associative array containing the form settings, fields, notifications, confirmations, and other properties (e.g. add-on settings).
Usage
// Getting a form property.
$title = rgar( $form, 'title' );
// Getting a nested form property.
$button_text = rgars( $form, 'button/text' );
// Setting a form property.
$form['description'] = 'the form description';
Properties
Basic
Prop | Type | Description |
---|---|---|
id | integer | The form ID. |
title | string | The form title. |
description | string | The form description. |
date_created | string | The date form was created in the format YYYY-MM-DD HH:MM:SS |
date_updated | null | Not used. |
is_active | boolean | The form active/inactive status. |
is_trash | boolean | Indicates if the form is in the trash. |
version | string | The Gravity Forms version used to create the form. |
fields | array | An indexed array of Field Objects. |
button | array | The submit Button Object. |
notifications | array | The Notifications Object. |
confirmations | array | The Confirmations Object. |
confirmation | null|array | Populated automatically during form submission with the Confirmation Object being used for the current submission. |
save | array | Since v1.9. See Save and Continue. |
personalData | array | Since v2.4. See Personal Data. |
pagination | null|array | Only applicable to multipage forms. See Pagination. |
lastPageButton | null|array | Only applicable to multipage forms. The Button Object for the previous button on the last page. |
nextFieldId | integer | Since 2.4.7. Calculated automatically every time the form is retrieved from the database. The form fields id properties are recursively checked to find the highest ID for all the fields in the form. The result is then incremented by 1. |
Form Layout
Prop | Type | Description |
---|---|---|
labelPlacement | string | The default location of the field labels. Possible values: top_label : Above the inputs.left_label : Left aligned; inline before the inputs.right_label : Right aligned; inline before the inputs. |
descriptionPlacement | string | Only used when labelPlacement is top_label .The default location of the field descriptions. Possible values: above : Above the inputs.below : Below the inputs. |
subLabelPlacement | string | Only applies to fields containing multiple inputs (e.g. Name). The default location of the field sub labels. Possible values: above : Above the inputs.below : Below the inputs. |
validationSummary | boolean | Since v2.5 Default: false Indicates if a summary of field validation errors should be listed at the top of the form. |
requiredIndicator | string | Since v2.5 Default: text Legacy Default: asterisk Defines what is used to indicate that a field is required. Possible values: text : Uses “(Required)”.asterisk : Uses “*”custom : Uses the value of the customRequiredIndicator setting. |
customRequiredIndicator | string | Since v2.5 Only used when requiredIndicator is custom .Allows a custom required indicator to be defined. |
cssClass | string | One or more space separated custom class names that will be added to the class attribute on the <form> tag. |
Save and Continue
The following properties are stored in an array assigned to $form['save']
.
Prop | Type | Description |
---|---|---|
enabled | boolean | Indicates if the save and continue later feature is enabled for the form. |
button | array | See Save and Continue Button. |
Save and Continue Button
The following properties are stored in an array assigned to $form['save']['button']
.
Prop | Type | Description |
---|---|---|
type | string | The button type. Default: link Possible values: link |
text | string | The button text. Default: Save and Continue Later |
Restrictions
Prop | Type | Description |
---|---|---|
limitEntries | boolean | Indicates if there is a limit on the number of entries this form can have. |
limitEntriesCount | integer | The total number of entries that can be created for this form during the period defined for limitEntriesPeriod . |
limitEntriesPeriod | string | The period the limit is based on. Possible values: An empty string to indicate the limit is based on the total number of entries that exist for the form regardless of when they were submitted. day : the limit resets daily.week : the limit resets weekly.month : the limit resets monthly.year : the limit resets yearly. |
limitEntriesMessage | string | The message that will be displayed when the limit is reached. |
scheduleForm | boolean | Indicates if the form should only be available during a scheduled period of time. |
scheduleStart | string | Date in the format (MM/DD/YYYY) that the form will become available. |
scheduleStartHour | integer | Hour (1 to 12) that the form will become available. |
scheduleStartMinute | integer | Minute that the form will become available. |
scheduleStartAmpm | string | Indicates if the scheduleStartHour is before or after midday.Possible values: am or pm |
scheduleEnd | string | Date in the format (MM/DD/YYYY) that the form will become unavailable. |
scheduleEndHour | integer | Hour (1 to 12) that the form will become unavailable. |
scheduleEndMinute | integer | Minute that the form will become unavailable. |
scheduleEndAmpm | string | Indicates if the scheduleEndHour is before or after midday.Possible values: am or pm |
schedulePendingMessage | string | The message to be displayed when the form is not yet available. |
scheduleMessage | string | The message to be displayed when the form is no longer available. |
requireLogin | boolean | Indicates if the user must be logged in to access the form. |
requireLoginMessage | string | The message to be displayed when the user isn’t logged in. |
Options
Prop | Type | Description |
---|---|---|
enableHoneypot | boolean | Indicates if the anti-spam honeypot feature is enabled. |
honeypotAction | string | Since v2.7 Determines if the submission is ignored or the entry is saved and marked as spam. Default: abort Possible values: abort or spam |
enableAnimation | boolean | Indicates conditional logic should use a slide animation when displaying and hiding fields and buttons. |
markupVersion | integer | Indicates which version of the form markup should be used. Possible values: 1 : Indicates legacy markup (pre-2.5) is enabled.2 : Indicates the accessible markup introduced in v2.5 should be used. |
Post Creation
The following properties impact the behaviour of the built-in post creation feature; they are populated in the form editor by configuring Post fields.
They don’t impact posts created by the Advanced Post Creation Add-On.
Prop | Type | Description |
---|---|---|
useCurrentUserAsAuthor | boolean | Indicates if the user logged in at the time the form is submitted should be the author. |
postAuthor | integer | The ID of the user to be set as the author. |
postCategory | string | For forms without a Post Category field, this property determines the default category that the post will be associated with when created. |
postContentTemplateEnabled | boolean | Determines if the post template functionality is enabled. When enabled, the post content will be created based on the template specified by postContentTemplate . |
postContentTemplate | string | Only applicable when postContentTemplateEnabled is true .Template to be used when creating the post content. Field merge tags (i.e. {Name:3} ) can be added to the template to insert user submitted values into the post content. |
postFormat | string | Determines the format that the Post should be created with. Possible values: Depends on the active theme. |
postStatus | string | Determines the status that the Post should be created with. Possible values: draft , pending , or publish |
postTitleTemplateEnabled | boolean | Determines if the post title template functionality is enabled. When enabled, the post title will be created based on the template specified by postTitleTemplate . |
postTitleTemplate | string | Only applicable when postTitleTemplateEnabled is true .Template to be used when creating the post title. Field merge tags (i.e. {Name:3} ) can be added to the template to insert user submitted values into the post title. |
Personal Data
The following properties are stored in an array assigned to $form['personalData']
.
Prop | Type | Description |
---|---|---|
preventIP | boolean | When enabled the IP address of the user submitting the form will not be saved. |
retention | array | See Retention Policy. |
exportingAndErasing | array | See Exporting and Erasing Data. |
Retention Policy
The following properties are stored in an array assigned to $form['personalData']['retention']
.
Prop | Type | Description |
---|---|---|
policy | string | Indicates how long the entries for this form should be retained. Possible values: retain : The default, retains them indefinitely, or until they are manually deleted.trash : The entries are trashed during a daily cron job once their retention period is up.delete : The entries are permanently deleted during a daily cron job once their retention period is up. |
retain_entries_days | integer | The number of days the entries are retained, relative to their date_created property, before being trashed or permanently deleted. |
Exporting and Erasing Data
The following properties are stored in an array assigned to $form['personalData']['exportingAndErasing']
.
Prop | Type | Description |
---|---|---|
enabled | boolean | Indicates if integration with the WordPress tools for exporting and erasing personal data is enabled. |
identificationField | integer|string | The ID of the field or entry property containing the user email address or ID. Possible values: The ID of a form email address field or created_by to use the ID of the logged in user who submitted the form. |
columns | array | Exporting and Erasing Columns |
Exporting and Erasing Columns
The following properties are stored in an array assigned to $form['personalData']['exportingAndErasing']['columns']
.
Prop | Type | Description |
---|---|---|
ip | array | Exporting and Erasing Column. |
source_url | array | Exporting and Erasing Column. |
user_agent | array | Exporting and Erasing Column. |
Exporting and Erasing Column
The following properties are stored in an array assigned to $form['personalData']['exportingAndErasing']['columns']
using the entry property as the key.
Prop | Type | Description |
---|---|---|
export | boolean | Indicates if integration with the WordPress feature for exporting personal data is enabled. |
erase | boolean | Indicates if integration with the WordPress feature for erasing personal data is enabled. |
Pagination
The following properties are stored in an array assigned to $form['pagination']
.
Prop | Type | Description |
---|---|---|
type | array | The progress indicator type. Possible values: percentage , steps , or none |
pages | array | Only applicable when type is or steps .An indexed array containing the page/step names. |
style | string | Only applicable when type is .The progress bar style. Possible values: blue , gray , green , orange , red , spring , blues , rainbow , or custom |
backgroundColor | string | Only applicable when type is and style is custom .The progress bar background color. A CSS hexadecimal color code. |
color | string | Only applicable when type is and style is custom .The progress bar text color. A CSS hexadecimal color code. |
display_progressbar_on_confirmation | boolean | Only applicable when type is .Indicates if the progress bar should start at 0% on the first page and end on 100% on the confirmation message instead of the last page. |
progressbar_completion_text | string | Only applicable when type is and display_progressbar_on_confirmation is true .The text to display when the progress bar is complete. |
Add-Ons
Add-Ons which extend the Add-On Framework and implement the form_settings_fields
method will store the values of those settings in associative arrays using the add-on slug as the key. Example:
$form['gravityformsrecaptcha'] = array(
'disable-recaptchav3' => '1',
);
Form JSON
This example shows how a form array would look when formatted as JSON for use by the Gravity Forms CLI Add-On.
{
"title": "My test form",
"description": "",
"labelPlacement": "top_label",
"descriptionPlacement": "below",
"button": {
"type": "text",
"text": "Submit",
"imageUrl": ""
},
"fields": [{
"type": "text",
"label": "My New Label",
"defaultValue": "Just testing",
"id": "1",
"visibility": "visible",
"formId": "14",
"pageNumber": 1
}, {
"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
}],
"version": "2.3-rc-5",
"id": "14",
"useCurrentUserAsAuthor": true,
"postContentTemplateEnabled": false,
"postTitleTemplateEnabled": false,
"postTitleTemplate": "",
"postContentTemplate": "",
"lastPageButton": null,
"pagination": null,
"firstPageCssClass": null,
"is_active": "1",
"date_created": "2018-04-12 16:51:40",
"is_trash": "0",
"notifications": {
"5acf8e9cf2b40": {
"id": "5acf8e9cf2b40",
"to": "{admin_email}",
"name": "Admin Notification",
"event": "form_submission",
"toType": "email",
"subject": "New submission from {form_title}",
"message": "{all_fields}"
}
},
"confirmations": {
"5acf8e9cf310a": {
"id": "5acf8e9cf310a",
"name": "Default Confirmation",
"isDefault": true,
"type": "message",
"message": "Thanks for contacting us! We will get in touch with you shortly.",
"url": "",
"pageId": "",
"queryString": ""
}
}
}