News & Updates -

Gravity Forms v1.7 Developer Notes

By Carl Hancock Published March 5, 2013

Gravity Forms v1.7 introduces powerful new changes to the Form Settings, Notifications and Confirmations.

All these fantastic changes come with some possible challenges to developers that have implemented hooks to extend or customize Gravity Forms default behavior related to these features. We have put a lot of thought into making this version as backwards compatible as possible, but with all the different hooks involved we cannot guarantee that you will not need to make some adjustments to your code.

The primary areas that were drastically changed within Gravity Forms are the Form Settings, Notification and Confirmations. If you have written any custom code around these areas, there is a chance your code will need to be adjusted, so please keep reading…

We hope this overview will help you better understand the underlying changes introduced in Gravity Forms v1.7 that will impact your custom code and will help you make the necessary changes to keep everything working properly with the new release. We have added documentation and examples for the new hooks introduced in Gravity Forms v1.7 to the Developer Documentation and our support team is here to answer any questions you may have.

Form Settings

Form Settings have been moved out of the Form Editor and given its own area within the Gravity Forms admin tool. This change gives us far more flexibility in introducing new features and accommodating customizations. The new Form Settings scraps the “Properties” and “Advanced” tabs in favor of a primary Form Settings page and the ability to add additional feature specific Form Settings pages using hooks.

The following are Form Settings related hooks that have been deprecated:

gform_properties_settings: You should now use gform_form_settings.
gform_advanced_settings: You should now use gform_form_settings.
gform_confirmation_settings: You should now use gform_confirmation_ui_settings.
gform_load_form_settings JS: This jQuery hook has been deprecated when used on the Form Editor as Form Settings are no longer located there. If you rely on this hook on the Form Editor you should use the gform_load_field_settings jQuery hook instead. When using this hook on the Form Settings page, the hook is still valid.
gform_before_update JS: You should now use the gform_pre_form_settings_save hook to handle updates on the new Form Settings page or gform_pre_form_editor_save jQuery hook to handle updates on the Form Editor page.

NOTE ON BACKWARDS COMPATIBILITY: As part of the change to abstract the Form Settings from the Form Editor, scripts and hooks that only applied to the Form Editor page will not be triggered on the new Form Settings pages. More specifically, the gform_editor_js hook will not be fired on the Form Settings page and functions in the form_editor.js script will not be available on the Form Settings page. Some functions required by the Form Settings page were moved from the form_editor.js script into a new script called form_admin.js. This new script contains common functions to both the Form Editor and Form Settings and will be available on both pages.

Also keep in mind that if you are targeting your scripts to be enqueued only on the Form Editor page and you have custom Form Settings, you will need to change your code so that scripts are enqueued on the new Form Settings page instead.

Notifications

We have completely re-designed the Notification functionality within Gravity Forms. Notifications still use the WordPress core wp_mail() function to send emails, however the interface has been overhauled and it now supports user-defined Notifications. Notifications have been moved to the new Form Settings page.

The most important change made with Notifications is the ability for the user to have complete control over defining the Notifications. There is no longer the concept of “Admin” and “User” Notifications. There is now just Notifications and the user can configure however many they’d like. All Notifications are now treated equally and conditional logic can be used to determine when and if a Notification is sent.

Several hooks and functions have been deprecated. They are still supported and working, however they will be removed in a future release. It is a good idea to update your code so that you are no longer relying on these deprecated functions.

The following are Notification related hooks that have been deprecated:

gform_disable_user_notification: You should now use gform_disable_notification.
gform_disable_admin_notification: You should now use gform_disable_notification.
gform_autoresponder_email: You should now use gform_notification.
gform_notification_format: You should now use gform_notification.
gform_user_notification_attachments: You should now use gform_notification.
gform_notification_format: You should now use gform_notification.
gform_notification_email: You should now use gform_notification.
GFCommon::send_user_notification(): You should now use GFCommon::send_notification().
GFCommon:send_admin_notification(): You should now use GFCommon::send_notification().
GFCommon::send_emails(): You should now use GFCommon::send_form_submission_notifications().

NOTE ON BACKWARDS COMPATIBILITY: When Gravity Forms 1.7 is installed, the existing configured User and Admin Notifications will be moved over to the new Notifications structure, but they will have a property assigned to them indicating that they are the “User” and “Admin” Notifications. This value will ensure that legacy functions and hooks that used to be based on the “User” and “Admin” Notification concept still function correctly. However, these properties will only be available on existing Notifications. New forms and new Notifications won’t have them. For that reason, it is very important that any code using any of these deprecated functions be updated as soon as possible to ensure that it will work with new forms and new Notifications.

Confirmations

As with Notifications, we have completely overhauled the features and capabilities of Confirmations in Gravity Forms. You are no longer limited to a single Confirmation and can configure any number of Confirmations that can be triggered using conditional logic.

There are primarily two main changes to Confirmations:

Confirmation settings have been moved to the new Form Settings. The markup for this page has changed and that means custom Confirmation settings will need to be changed to use this new markup format. The old format will still “work”, but will be inconsistent with the other settings. The gform_confirmation_settings hook has been deprecated, and you should now use gform_confirmation_ui_settings.
Multiple confirmations can now be configured with conditional logic and the appropriate one will be executed/displayed appropriately depending on user selection and the conditional logic configuration. Only a single Confirmation will be executed when the form is submitted. If multiple Confirmations exist and their conditional logic is triggered, only the first Confirmation triggered would be executed. We are considering enabling multiple Confirmations to be executed and returned if they are configured as a Text Confirmation, however that is not included in this release.

Everything here should be backwards compatible, but if you have custom code dealing with changing confirmations programmatically, it is probably a good idea to test it as soon as possible and update it so that it works as expected.

Merge Tags

Support for custom merge tags has been altered. Prior to 1.7, custom merge tags could be added via the gform_custom_merge_tags hook. This hook is now deprecated in favor of the gform_merge_tags hook.

It is important to note that while the gform_custom_merge_tags hook is a PHP hook; the new gform_merge_tags hook is a Javascript hook. The merge tag system has been revamped in 1.7 to create a more powerful and flexible Javascript-powered method for providing a list of merge tags available for the corresponding input.

Using the gform_merge_tags is very similar to the gform_custom_merge_tags hook. The primary difference is that you must specify which “group” you would like to add your merge tag to. Previously, all custom merge tags were added to the “custom” group. Additionally, the new hook gives you complete control over the merge tags, allowing you to add/remove merge tags as needed.

For additional usage information, please refer to the gform_merge_tags documentation.