Description
Use this filter 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.
//the 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
The following would apply to all forms:
add_filter( 'gform_confirmation_anchor', 'your_function_name' );
To target a specific form append the form id to the hook name. (format: gform_confirmation_anchor_FORMID)
add_filter( 'gform_confirmation_anchor_5', 'your_function_name' );
Parameters
- $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).
- Set $anchor to true -> Page will scroll to the position where the form is located.
- Set $anchor to false -> Page will not scroll. For AJAX forms, the page scroll position won’t change when the form is submitted. For non-AJAX forms, the page will remain at the top of document after being reloaded.
- Set $anchor to any numeric value -> Page will be scrolled to the specified pixel value from the top of the document.
- $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 should be placed in the functions.php file of your active theme.
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()