Description
The gform_confirmation_anchor filter allows developers to enable or disable the confirmation anchor functionality that automatically scrolls the page to the confirmation text or validation message upon submission. This also takes effect when browsing between pages of a multi-page form. The page may also be forced to scroll to a specified distance (pixel) from the top of the page. This hook is useful when embedding forms in a long page.
When the anchor exists, the page scrolls to the top of the form. For non-AJAX forms without the anchor, the page remains at the top of the page upon reload. For AJAX forms without the anchor, the page will not move when the form content is updated. Depending on the page layout, padding and margin changes associated with displaying validation errors may make it appear that the page has scrolled.
When the anchor is set to true, the following HTML is added before the opening form tag.
// 80 is the form id
<div id='gf_80' class='gform_anchor' tabindex='-1'></div>
When true, the bookmark for the anchor (#gf_80 in this example) is also added to the action on the form tag.
<form method='post' enctype='multipart/form-data' id='gform_80'
action='/wp.dev/?gf_page=preview&id=80#gf_80'>
Usage
Applies to all forms.
add_filter( 'gform_confirmation_anchor', 'your_function_name' );
Applies to a specific form. In this case, form id 5.
add_filter( 'gform_confirmation_anchor_5', 'your_function_name' );
Parameters
| Parameter | Type | Description |
|---|---|---|
$anchor | bool | int | Indicates how the anchor will behave. The default is true when AJAX is enabled or for multi-page non-AJAX forms (anchor present), and false for single page non-AJAX forms (no anchor).
|
$form | Form Object | The current form. Available from Gravity Forms 1.9.17.12. |
Examples
1. Enable for all forms
The following example enables the confirmation anchor on all forms.
add_filter( 'gform_confirmation_anchor', '__return_true' );
2. Disable for a specific form
The following example disables the confirmation anchor for form with ID 5.
add_filter( 'gform_confirmation_anchor_5', '__return_false' );
3. Set scroll distance
The following example causes all AJAX enabled forms to scroll to 20 pixels from the top of the document after being submitted. Only AJAX enabled forms can set the scroll distance.
add_filter( 'gform_confirmation_anchor', function() {
return 20;
} );
Placement
This code can be used in the functions.php file of the active theme, a custom functions plugin, a custom add-on, or with a code snippets plugin.
See also the PHP section in this article: Where Do I Put This Code?
Since
This filter was added in Gravity Forms version 1.3.13.
Ability to pass an integer for $anchor added in version 1.6.
$form parameter added in version 1.9.17.12.
Source Code
This filter is located in the following methods in form_display.php:
- GFFormDisplay::get_form()
- GFFormDisplay::get_confirmation_message()
- GFFormDisplay::replace_save_variables()
- GFFormDisplay::handle_save_email_confirmation()
- GFFormDisplay::handle_save_confirmation()