Developer Docs

(Administration)
(Entry Object)
Line 241: Line 241:
</pre>
</pre>
For details about each property, visit the [[Entry Object]] page.
For details about each property, visit the [[Entry Object]] page.
 +
 +
== Entry Meta <span class="new"><span class="new-label">New with GF v1.6</span></span> ==
 +
 +
Entries now support custom meta! You can retrieve, update and remove an entry's custom meta using these functions:
 +
 +
*  [[gform_get_meta|gform_get_meta()]]
 +
*  [[gform_update_meta|gform_update_meta()]]
 +
*  [[gform_delete_meta|gform_delete_meta()]]
== [[Role Management]] ==
== [[Role Management]] ==

Revision as of 19:57, 25 August 2011

Contents

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

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_column_input (new in v. 1.6)
    This filter can be used to specify a different input type for a column in a list field. Currently supported field types are "select" (Dropdown) and "text" (Text Field).
  • gform_counter_script
    Use this filter to change the initialization script for the textarea counter script. Can be used to specify different initialization parameters.
  • gform_countries
    This filter can be used to change the list of countries displayed in the address field
  • gform_date_min_year (new in v. 1.6)
    Use this filter to specify the min year displayed in the date field's year drop down
  • gform_date_max_year (new in v. 1.6)
    Use this filter to specify the max year displayed in the date field's year drop down
  • 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_content
    Use this filter to specify the contents of a field (label and input). Can be used to change the way an existing field type is displayed or to implement a custom field type. Similar to gform_field_input, but provides more flexibility.
  • 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_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_form_tag
    Use this filter to change Gravity Forms <form> tag.
  • gform_input_mask_script (new in v. 1.6)
    Use this filter to change the initialization script for the input mask script. Can be used to specify different initialization parameters.
  • 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).

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_after_submission (new in v. 1.6)
    Use this hook to perform actions after the entry has been created (i.e. feed data to third party applications).
  • 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_field_validation (new in v. 1.6)
    Use this filter to create custom validation logic for a field.
  • 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_paging
    Use this hook to perform actions after going to the next or previous page on a multi-page form.
  • 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_notification_format (new in v. 1.6)
    Use this filter to change the notification email format (text or html)
  • gform_ajax_spinner_url
    Use this filter to change the spinner icon that is displayed on AJAX forms when the form is submitted
  • gform_akismet_fields (new in v. 1.6)
    Use this filter to specify the fields that are sent to the Akismet anti-spam service.


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_addon_navigation
    Use this filter to add a sub-menu item under the "Forms" menu.
  • 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_after_delete_field
    Use this action hook to perform actions right after a field is deleted from a form.
  • gform_after_delete_form
    Use this action hook to perform actions right after a form is deleted.
  • 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_before_delete_field
    Use this action hook to perform actions right before a field is deleted from a form.
  • gform_before_delete_form
    Use this action hook to perform actions right before a form is deleted.
  • gform_delete_lead
    Use this hook to perform actions when an entry is deleted.
  • 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_enable_password_field
    Use this filter to enable the password field. Useful when developing add-ons that require a password field.
  • gform_entries_column
    Use this action to inject markup to any non-first column of every entry in the entry list grid.
  • gform_entries_first_column
    Use this action to inject markup in the first column of every entry in the entry list grid.
  • gform_entries_first_column_actions
    This action hook fires at the end of the action links of every entry in the entry grid list. Useful when adding a custom action link.
  • 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_export_separator (new in v. 1.6)
    Use this filter to change the column separator character for the entry export file. The default separator is a comma (,)
  • gform_get_field_value (deprecated. Use gform_get_input_value instead)
    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_input_masks (new in v. 1.6)
    Use this filter to edit the list of built-in input masks that are displayed in the Text Field input mask setting. Useful when adding a new custom input mask that will be used repeatedly.
  • gform_get_input_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_type_title (new in v. 1.6)
    When adding a new field type, use this filter to assign a title to the new type.
  • 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_print_entry_footer
    Use this action hook to add a custom footer to the print entry screen
  • gform_print_entry_header
    Use this action hook to add a custom header to the print entry screen
  • 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_product_info
    Use this filter to manipulate the list of products displayed in the entry detail and sent to third party via Add-Ons such as the PayPal Add-On.
  • [[gform_settings_{$section_name}]]
    Use this action hook to create a custom settings page under the main Gravity Forms settings. Note: Requires a previous call to GFSettings::add_settings_page().
  • gform_tooltips
    Use this filter to manipulate the tooltips that are displayed throughout Gravity Forms administration pages
  • gform_default_notification
    Use this filter to disable the default admin notification created for new forms.

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)
  • gform_product_total
    Fires right before updating the Total value on forms with pricing fields. Allows users to manipulate the Total value based on custom logic.

Other

  • 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.

Entry Meta New with GF v1.6

Entries now support custom meta! You can retrieve, update and remove an entry's custom meta using these functions:

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.

Search the Documentation