Form Object

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

PropTypeDescription
idintegerThe form ID.
titlestringThe form title.
descriptionstringThe form description.
date_createdstringThe date form was created in the format YYYY-MM-DD HH:MM:SS
date_updatednullNot used.
is_activebooleanThe form active/inactive status.
is_trashbooleanIndicates if the form is in the trash.
versionstringThe Gravity Forms version used to create the form.
fieldsarrayAn indexed array of Field Objects.
buttonarrayThe submit Button Object.
notificationsarrayThe Notifications Object.
confirmationsarrayThe Confirmations Object.
confirmationnull|arrayPopulated automatically during form submission with the Confirmation Object being used for the current submission.
savearraySince v1.9. See Save and Continue.
personalDataarraySince v2.4. See Personal Data.
paginationnull|arrayOnly applicable to multipage forms. See Pagination.
lastPageButtonnull|arrayOnly applicable to multipage forms.
The Button Object for the previous button on the last page.
nextFieldIdintegerSince 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

PropTypeDescription
labelPlacementstringThe 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.
descriptionPlacementstringOnly used when labelPlacement is top_label.
The default location of the field descriptions.
Possible values:
above: Above the inputs.
below: Below the inputs.
subLabelPlacementstringOnly 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.
validationSummarybooleanSince v2.5
Default: false
Indicates if a summary of field validation errors should be listed at the top of the form.
requiredIndicatorstringSince 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.
customRequiredIndicatorstringSince v2.5
Only used when requiredIndicator is custom.
Allows a custom required indicator to be defined.
cssClassstringOne 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'].

PropTypeDescription
enabledbooleanIndicates if the save and continue later feature is enabled for the form.
buttonarraySee Save and Continue Button.

Save and Continue Button

The following properties are stored in an array assigned to $form['save']['button'].

PropTypeDescription
typestringThe button type.
Default: link
Possible values: link
textstringThe button text.
Default: Save and Continue Later

Restrictions

PropTypeDescription
limitEntriesbooleanIndicates if there is a limit on the number of entries this form can have.
limitEntriesCountintegerThe total number of entries that can be created for this form during the period defined for limitEntriesPeriod.
limitEntriesPeriodstringThe 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.
limitEntriesMessagestringThe message that will be displayed when the limit is reached.
scheduleFormbooleanIndicates if the form should only be available during a scheduled period of time.
scheduleStartstringDate in the format (MM/DD/YYYY) that the form will become available.
scheduleStartHourintegerHour (1 to 12) that the form will become available.
scheduleStartMinuteintegerMinute that the form will become available.
scheduleStartAmpmstringIndicates if the scheduleStartHour is before or after midday.
Possible values: am or pm
scheduleEndstringDate in the format (MM/DD/YYYY) that the form will become unavailable.
scheduleEndHourintegerHour (1 to 12) that the form will become unavailable.
scheduleEndMinuteintegerMinute that the form will become unavailable.
scheduleEndAmpmstringIndicates if the scheduleEndHour is before or after midday.
Possible values: am or pm
schedulePendingMessagestringThe message to be displayed when the form is not yet available.
scheduleMessagestringThe message to be displayed when the form is no longer available.
requireLoginbooleanIndicates if the user must be logged in to access the form.
requireLoginMessagestringThe message to be displayed when the user isn’t logged in.

Options

PropTypeDescription
enableHoneypotbooleanIndicates if the anti-spam honeypot feature is enabled.
honeypotActionstringSince v2.7
Determines if the submission is ignored or the entry is saved and marked as spam.
Default: abort
Possible values: abort or spam
enableAnimationbooleanIndicates conditional logic should use a slide animation when displaying and hiding fields and buttons.
markupVersionintegerIndicates 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.

PropTypeDescription
useCurrentUserAsAuthorbooleanIndicates if the user logged in at the time the form is submitted should be the author.
postAuthorintegerThe ID of the user to be set as the author.
postCategorystringFor forms without a Post Category field, this property determines the default category that the post will be associated with when created.
postContentTemplateEnabledbooleanDetermines if the post template functionality is enabled. When enabled, the post content will be created based on the template specified by postContentTemplate.
postContentTemplatestringOnly 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.
postFormatstringDetermines the format that the Post should be created with.
Possible values: Depends on the active theme.
postStatusstringDetermines the status that the Post should be created with.
Possible values: draft, pending, or publish
postTitleTemplateEnabledbooleanDetermines if the post title template functionality is enabled. When enabled, the post title will be created based on the template specified by postTitleTemplate.
postTitleTemplatestringOnly 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'].

PropTypeDescription
preventIPbooleanWhen enabled the IP address of the user submitting the form will not be saved.
retentionarraySee Retention Policy.
exportingAndErasingarraySee Exporting and Erasing Data.

Retention Policy

The following properties are stored in an array assigned to $form['personalData']['retention'].

PropTypeDescription
policystringIndicates 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_daysintegerThe 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'].

PropTypeDescription
enabledbooleanIndicates if integration with the WordPress tools for exporting and erasing personal data is enabled.
identificationFieldinteger|stringThe 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.
columnsarrayExporting and Erasing Columns
Exporting and Erasing Columns

The following properties are stored in an array assigned to $form['personalData']['exportingAndErasing']['columns'].

PropTypeDescription
iparrayExporting and Erasing Column.
source_urlarrayExporting and Erasing Column.
user_agentarrayExporting 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.

PropTypeDescription
exportbooleanIndicates if integration with the WordPress feature for exporting personal data is enabled.
erasebooleanIndicates 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'].

PropTypeDescription
typearrayThe progress indicator type.
Possible values: percentage, steps, or none
pagesarrayOnly applicable when type is percentage or steps.
An indexed array containing the page/step names.
stylestringOnly applicable when type is percentage.
The progress bar style.
Possible values: blue, gray, green, orange, red, spring, blues, rainbow, or custom
backgroundColorstringOnly applicable when type is percentage and style is custom.
The progress bar background color.
A CSS hexadecimal color code.
colorstringOnly applicable when type is percentage and style is custom.
The progress bar text color.
A CSS hexadecimal color code.
display_progressbar_on_confirmationbooleanOnly applicable when type is percentage.
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_textstringOnly applicable when type is percentage 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": ""
        }
    }
}