Developer Docs

Revision as of 15:47, 17 March 2011

Introduction

We believe in keeping Gravity Forms simple and easy to use, and a lot of thought goes into adding new functionality. Still, users often find the need to add/modify functionality to meet their needs.

This section of the documentation offers guidelines and references for anyone wishing to modify or extend Gravity Forms.

Add-on Developer Docs

• PayPal Add-on Developer Docs
• User Registration Add-on Developer Docs

Hooks and Filters

Following is a list of available hooks and filters.

Form Loading

The following filters can be used to manipulate the form data before the form gets displayed to the screen. Tasks such as adding drop down items dynamically or pre-populating field values can be accomplished using them.

• gform_countries

  This filter can be used to change the list of countries displayed in the address field

• gform_enqueue_scripts

  Use this action hook to enqueue scripts to the page. Useful when creating custom field types that require additional scripts

• gform_field_input

  Use this filter to specify the field's <input> tag. It can be used to change an existing field type or to implement a custom field type

• gform_field_value_$parameter_name

  Use this filter to add a default value to the field specified by $parameter_name.

• gform_field_choices

  Use this filter to manipulate checkbox and radio items. Can be used to allow HTML content to be displayed

• gform_field_css_class

  Use this filter to change the field's CSS class(es). Useful to dynamically assign a CSS class to a field.

• gform_form_tag

  Use this filter to change Gravity Forms <form> tag.

• gform_pre_render

  Use this filter to manipulate the Form Object before the form is displayed.

• gform_submit_button

  Use this filter to change Gravity Forms submit button. Can be used to implement the Sliding Door CSS technique

• gform_tabindex

  Use this filter to specify the tab index start value or to disable the tabindex attribute

Sublabels

In cases where translating Gravity Forms is not an option, the following filters can be used to change the sublabels of multi-input fields (i.e Name and Address).

• gform_name_prefix
• gform_name_first
• gform_name_last
• gform_name_suffix
• gform_address_street
• gform_address_street2
• gform_address_city
• gform_address_state
• gform_address_zip
• gform_address_country
• gform_postimage_file
• gform_postimage_title
• gform_postimage_caption
• gform_postimage_description
• gform_order_label

Form Submission

The following filters can be used to manipulate the entry data when the user submits the form. Tasks such as integrating with third party systems and dynamic notification routing can be accomplished using them.

• gform_confirmation

  Use this filter to dynamically change the form confirmation message or the redirect URL

• gform_disable_user_notification

  Use this filter to disable all user notification emails

• gform_disable_admin_notification

  Use this filter to disable all admin notification emails

• gform_disable_post_creation

  Use this filter to disable post creation when submitting a Gravity Form.

• gform_file_permission

  Use this filter to change the default permissions of uploaded files.

• gform_pre_submission

  Use this hook to perform actions after form validation, but before sending notifications and storing the entry data.

• gform_pre_submission_filter

  Use this hook to manipulate the Form Object before sending notifications and storing entry data.

• gform_upload_path

  Use this hook to change the path where files are uploaded by the File Upload field.

• gform_post_data

  Use this filter to manipulate submitted Post field data before the Post is created.

• gform_post_submission

  Use this hook to perform actions after the entry has been created (i.e. feed data to third party applications).

  The Entry Object is available to this hook and contains all submitted values

• gform_save_field_value

  Use this filter to change the field's value before saving it to the database. Use in conjunction with gform_get_field_value to perform low level transformations, such as encrypting/decrypting a field

• gform_is_duplicate

  Use this hook to specify a custom duplicate validation logic for fields marked with the 'No Duplicates' rule

• gform_confirmation_anchor

  Use this filter to enable the confirmation anchor that will automatically scroll the page to the confirmation text upon submission. Useful when embedding forms in long pages.

• gform_validation

  Use this filter to create custom validation logic.

• gform_validation_message

  Use this filter to change the main validation message that is displayed when the form fails validation.

• gform_duplicate_message

  Use this filter to change the the message that is displayed when a field fails the duplicate value validation.

• gform_autoresponder_email

  Use this filter to dynamically change the TO email for user notifications.

• gform_notification_email

  Use this filter to dynamically change the TO email for admin notification.

• gform_ajax_spinner_url

  Use this filter to change the spinner icon that is displayed on AJAX forms when the form is submitted

Administration

The following filters are fired within the Gravity Forms administration allowing the customization of certain elements.

• gform_add_field_buttons

  Use this filter to add/remove field type buttons to the form editor screen

• gform_address_types

  Use this filter to add support for a new address type (i.e. another country)

• gform_admin_pre_render

  Use this filter to manipulate the Form Object before an entry is displayed on the entry detail page in the administration. If you have used gform_pre_render filter to dynamically add items to a drop down field, you may also want to add those items to the entry detail screen to allow administrators to properly edit the entry.

• gform_author_dropdown_args

  Use this filter to change the author list displayed on post fields. Do that by specifying the $args parameter that will be passed to the wp_dropdown_users($args) to retrieve the author list

• gform_editor_js

  This action hook can be used to inject Javascript into the form editor page

• gform_entries_field_value

  Use this filter to change the field's value before getting displayed on the Entry list page. Useful when creating custom field types that require special formatting for the entry list

• gform_entry_field_value

  Use this filter to change the field's value before getting displayed on the Entry detail page. Useful when creating custom field types that require special formatting when displayed

• gform_get_field_value

  Use this filter to change the field's value after being retrieved from the database. Use in conjunction with gform_save_field_value to perform low level transformations, such as encrypting/decrypting a field

• gform_save_field_value

  Use this filter to change the field's value before saving it to the database. Use in conjunction with gform_get_field_value to perform low level transformations, such as encrypting/decrypting a field

• gform_entries_first_column_actions

  Use this action hook to add extra action links to the entry row on the entry list page.

• gform_entry_info

  Use this hook to add custom entry information to the Info area on the Entry detail page

• gform_field_advanced_settings

  Use this filter to create a new field settings under the Advanced tab. Useful when implementing a new custom field type that requires custom settings.

• gform_field_standard_settings

  Use this filter to create a new field settings under the Standard tab. Useful when implementing a new custom field type that requires custom settings.

• gform_predefined_choices

  Use this filter to manipulate and/or add new predefined choices to the selection fields (i.e. Checkbox, Drop Down, Multiple Choice)

• gform_tooltips

  Use this filter to manipulate the tooltips that are displayed throughout Gravity Forms administration pages

Javascript

The following events are fired via jQuery and allow custom client side scripts to be executed.

• gform_page_loaded

  Fires on multi-page forms when changing pages (i.e. going to the next or previous page)

Other

• gform_address_display_format

  Fires when formatting addresses for display. Can be used to change the way addresses are formatted.

• gform_currencies

  This filter allows existing currencies to be modified and new currencies to be created.

Form Object

The Form Object is the main object in Gravity Forms. It contains all properties of a particular form (i.e. form title, fields, notification, scheduling, etc...). This object is available to most of the Gravity Forms hooks above and can be manipulated to change the way the form is displayed, notifications are sent, etc...

It is formatted as an associative array (i.e. $form["title"] retrieves the form title). For details about each property, visit the Form Object page.

Entry Object

The Entry Object contains all properties of a particular entry (i.e. date created, client IP, submitted field values, etc...). It is formatted as an associative array with field ids being the key to get the field data.

$entry["date_created"]; //returns the entry date
$entry["1"];              //returns the value associated with field 1

For details about each property, visit the Entry Object page.

Role Management

Gravity Forms introduces new capabilities to the WordPress Role system. For more information, check out the Role Management page.

Samples

Following are some samples on using Gravity Forms' hooks to modify/extend Gravity Forms functionality.

• Formatting Post Content when using Post Fields
• Populating a Drop Down field with posts of a certain category
• Routing notification to emails submitted in the form