Preparing Your Sites for Gravity Forms Legacy Markup EOL

General Discussion
,
1

The Announcement

Gravity Forms has announced a significant change coming with version 3.1: the complete removal of legacy markup support. This marks the end of an era that began in 2009 when the original markup structure was introduced. Though the modern markup standard has been available since version 2.5 (released April 2021), many sites still rely on the legacy version for their forms.

First, A Reassurance: While this change is significant, many Gravity Forms users won’t be affected at all. If you’re using forms with default styling and no custom code modifications, you can safely switch to the new markup without concern. This guide is intended as a resource for those employing custom CSS, JavaScript, or complex form customizations.

While there is no date for when version 3.1 will arrive, we can reference the Gravity Forms Changelog for historical release dates in order to project some idea for when 3.1 may land.

  • 2.5: April 2021
  • 2.6: March 2022
  • 2.7: January 2023
  • 2.8: December 2023
  • 2.9: November 2024
  • 3.0: September/October 2025 (AI projection)
  • 3.1: August/September 2026 (AI projection)

There is no guarantee that 3.1 will be released on this historical cadence, but this projection might help you properly set plans for migration from legacy markup. This timeline should give developers and site owners a window to prepare their sites for this important transition.

When this change takes effect, all forms will automatically default to the standard markup structure, regardless of their current settings. This forced migration means that forms currently using legacy markup should be reviewed and updated before the release of version 3.1 to ensure continued functionality.

While most forms will likely continue to work without issue once rendered with the new markup, there will be instances (especially where customizations have been made) for which changes and updates will be needed to ensure compatibility.

Why It’s Important

The shift from legacy markup marks a fundamental change in how Gravity Forms renders its forms. The implications are significant for site owners and developers alike. The modern markup introduced in version 2.5 brought substantial improvements in several key areas:

Accessibility: The new markup structure implements proper semantic HTML elements, such as using for multi-input fields and for field labels, making forms more accessible to users relying on screen readers and other assistive technologies.

Performance: The modern markup includes optimizations like deferred script loading and footer placement, contributing to better overall form performance.

Modern Web Standards: The transition from table-based layouts to div-based structures and the implementation of CSS variables for styling reflects current web development best practices and has paved the way for the implementation of the new theme framework.

If your forms still use legacy markup, they might experience issues once version 3.1 is released. These potential problems include:

  • Broken layouts due to outdated CSS targeting deprecated markup structures
  • JavaScript functionality issues where scripts depend on legacy markup elements
  • Non-functioning CSS ready classes that were designed for the legacy structure
  • Compatibility issues with newer Gravity Forms features, like the Image Choice Field

The importance of addressing this change proactively cannot be overstated. Rather than waiting for the forced transition, taking steps now to update your forms ensures a smooth transition, allows you to take advantage of the improved features and accessibility benefits that come with the modern markup, and ensures your forms function without issue once Gravity Forms 3.1 hits.

Outlining a Plan of Action

Before making major moves and modifications to the forms across your sites, let’s first set a strategy. I would propose the following:

  1. Scope the project (make a list of which forms on which sites need attention).
  2. Audit forms (determine the nature of changes required by each form).
  3. Deploy a test method (identify and prep a test environment).
  4. Do the dirty work (move form-by-form, ensuring compatibility).
  5. Switch the markup (publicly deploy markupVersion:2)

Scoping the Project

(click to expand) make a list of which forms on which sites need attention

One of the first challenges in preparing for this transition is identifying which forms are still using legacy markup. This can be an overwhelming task when managing multiple sites or overseeing a site with hundreds of forms. Let’s give ourselves a few tools for making this task a breeze.

To check forms one-by-one, access the form editor for each and see whether a banner notice is displayed indicating use of legacy markup.

For sites with multiple forms, you can quickly identify those not using the newer markup version (.i.e. those still using legacy markup) by running the following SQL query in your database:

SELECT *
FROM wp_gf_form_meta
WHERE display_meta NOT LIKE '%\"markupVersion\":2%';

Note: If your database tables have a different prefix, alter the SQL command accordingly.

Alternatively, you can add the following snippet to any sites running Gravity Forms so as to identify forms with legacy markup directly in your form list.

// Add form list column showing markup version
add_filter( 'gform_form_list_columns', function( $columns ) {
    $columns['markup_version'] = esc_html__( 'Markup Version' );
    return $columns;
} );

add_action( 'gform_form_list_column_markup_version', function( $item ) {

    $form = GFAPI::get_form( rgobj( $item, 'id' ) );
    $is_standard = rgar( $form, 'markupVersion' ) === 2;
    
    echo $is_standard 
    ? '<span style="color: #00a32a;">✓ ' . esc_html__( 'Standard' ) . '</span>'
    : '<span style="color: #d63638;">⚠ ' . esc_html__( 'Legacy' ) . '</span>';
    
} );

Consider PHP Code Keeper for Gravity Forms when adding custom PHP snippets.

Auditing Forms

(click to expand) determine the nature of changes required by each form

After identifying the forms currently running on legacy markup, the next step is to audit them to see whether they may need any updates for compatibility with markupVersion:2. I recommend checking forms for the following common compatibility issues.

Ready Classes

Are there any CSS ready classes in use? To inspect for CSS ready classes, you will need to check each field of the form and determine whether any official ready classes are present under the Field Settings → Appearance → Custom CSS Class. You can also check whether there may be any form-level ready classes added to Form → Settings → Form Layout → CSS Class Name.

Gravity Forms 3.0 introduces notices in the form editor when any ready classes are in use.

Consider Gravity Hopper Field Hinting for quick identification of field classes.

Legacy-Specific Selectors

If you are employing any custom CSS or JS on forms, there is a decent chance that certain selectors in your code may fail to work when moving away from legacy markup. Here is a non-comprehensive overview of markup changes that may affect the selectors you will need to use:

  • Field Wrapper: <li> is now either <div> or <fieldset> depending on whether field is single-input or multi-input.
  • Multi-Input Field Labels: <label> is now <legend>.
  • List Field: Refactored for improved accessibility.
    • All <table> tags replaced with <div> tags.
    • Add/remove <a> tags replaced with <button>.

Custom CSS

When checking for custom CSS, please note that there are various places in which such CSS may reside. Reference Where to Put Your Custom CSS for common ways CSS is added to forms.

Before updating CSS across your forms, you should determine the most suitable form theme for your site. The default theme for all forms can be managed site-wide at Forms → Settings → Default Form Theme. Gravity Forms comes packaged with two form themes. The Gravity Forms 2.5 Theme will inherit most styles from the active theme, while Orbital will be more opinionated with styles provided by Gravity Forms. This theme can also be set at the embed level for each form. When using the Orbital Theme, some basic default styles can be set globally using the filter gform_default_styles. These will cascade to elements throughout the form. The newer markup paved the way for the Theme Framework, which makes wide use of CSS variables so that custom styles can be made in a more consistent fashion. However, making changes is best handled in a way different from that with which forms have been historically styled. The styling is now built largely upon CSS variables, providing a more consistent and maintainable approach to form styling. You can explore these variables in the files located in the assets/css/dist directory or by using your browser’s inspector to identify variables in use on specific form elements.

Custom Javascript

When checking for custom Javascript, please note that there are various places in which such scripts may reside. Reference Where Do I Put This Code? for common ways JS is added to forms.

Third-Party Plugins

It has been quite some time since the newer markup was introduced, so most third-party plugins have already released versions to address any compatibility issues. Still, it will be good to check whether any may have outstanding compatibility issues.

Deploying a Test Method

(click to expand) identify and prep a test environment

Before making any public changes to your production forms, it’s crucial to have a robust testing strategy in place. Gravity Forms provides several methods to safely test the transition from legacy to modern markup.

As a user with an administrator role on a site, you can implement a selective testing approach using the gform_enable_legacy_markup filter. This allows you to view all forms with the new markup while maintaining legacy markup for regular users:

add_filter( 'gform_enable_legacy_markup', function( $is_enabled, $form ) {

    return ! current_user_can( 'administrator' );

}, 10, 2 );

Do note that while running this snippet will present different markup per user role, any changes to the form will apply for all users.

Another practical approach is to create a development or staging environment where you can freely test forms without affecting your live site. This method allows for comprehensive testing of not just the forms themselves, but also any custom code, styling, or integrations that might be affected by the markup changes. If using this approach, you will want to be sure to have in mind a strategy for merging any changes back to your live site.

Consider Form Vault and/or Gravity Hopper Form Network for syncing form changes.

Nitty-Gritty Code Wrangling

(click to expand) move form-by-form, ensuring compatibility

With a test environment in place and all issues identified, you’re almost ready to dig in and start making necessary changes.

IMPORTANT: Before proceeding, and as a precautionary measure, be sure to make a full backup of your database.

Having secured a backup and having your test environment in place, you can begin making changes to each form and testing those updates against the new markup to ensure your form continues to look and function as you need.

Consider Gravity Forms Code Chest when adding form-specific CSS & JS.

Should you need to contract a developer for handling complex customizations, you can check out these recommended channels for connecting with someone.

Switching the Markup

(click to expand) publicly deploy markupVersion:2

Once any changes have been made and tested, the next step will be to switch legacy markup off for the form. This can be handled on a form-by-form basis by disabling the toggle at Form Settings → Form Options → Enable legacy markup. Should you find this setting not available for a form running legacy markup, you can add the following line of PHP code to expose the setting:

add_filter( 'gform_show_legacy_markup_setting', '__return_true' );

If you would like to instead deploy the change immediately to all forms across a site, you can include the following snippet:

add_filter( 'gform_enable_legacy_markup', '__return_false' );

For the Good of Forms Everywhere

Remember that the transition to modern markup isn’t just about maintaining functionality— it’s an opportunity to improve your forms’ accessibility, performance, and user experience. While the change may require some effort, the long-term benefits of using modern, semantic markup make it well worth the investment.

Keep this resource guide bookmarked and refer back to it as you work through your transition process. The Gravity Forms team continues to update their documentation and provide support as we approach the release of version 3.1.

Resources and Support

To help ensure a successful transition from legacy to modern markup, Gravity Forms provides several valuable resources and support channels.

Official Documentation

Development Tools

Community Support

Professional Assistance

Disclaimer : Third-party plugins or code snippets that are provided or referenced by our Support Team or documentation, are provided as suggestions only. We do not evaluate, test, guarantee or officially support third-party solutions or code-snippets. You are wholly responsible for determining if any suggestion or code snippet provided is sufficient to meet the functional, security, legal, ongoing cost and support needs of your project, as well as testing and confirming performance across future product updates.

If you have tools, tips, or tricks for those making this move, share them in reply – for the good of forms everywhere.

1 Like