🎉 Celebrate with 10% OFF on All Products! Use Code: GFEX10 Or Buy Any 2+ Items for 30% OFF with Code: GFEX30!

Gravity Forms Legacy Markup & 3.x Migration Assistant Setup Guide

Updated 12 min read Gravity Forms Integrations A–Z
On this page
  1. What legacy markup is, and why it matters now
  2. What you need
  3. Install and activate
  4. How it differs from other tools
  5. Step 1: the Forms tab
  6. Step 2: the readiness scan (read-only)
  7. Reading the findings
  8. Step 3: the class conversion
  9. Step 4: the side-by-side preview
  10. Step 5: the dry run
  11. Step 6: the bulk switch
  12. Step 7: backups and rollback
  13. Who can do what
  14. Notes for Gravity Forms 2.9
  15. A sensible order of work
  16. What the add-on does not do
  17. Privacy and data

The Gravity Forms Legacy Markup & 3.x Migration Assistant add-on helps you move every form on your site off legacy markup safely, before legacy markup is removed in a future Gravity Forms version. It finds what would break when a form switches, converts the old CSS Ready Classes to the modern layout settings, shows each form side by side with legacy and modern markup, lists every change in a dry run, and switches forms in bulk with a backup of each form first and a one-click rollback. This guide covers installing the add-on, running the readiness scan and reading its findings, the class conversion, the preview and the dry run, the bulk switch and the backups, who can do what, and what the add-on deliberately does not do.

What legacy markup is, and why it matters now

Gravity Forms 2.5 introduced a new way of writing the HTML of a form: fields are div elements in a CSS grid instead of items in a ul list, the form title is an h2, error messages have a new wrapper, and the layout comes from the form editor’s column settings instead of CSS Ready Classes such as gf_left_half. Forms created before 2.5 kept the old HTML, called legacy markup, so that existing sites did not change overnight. Each of those forms has a setting, Enable legacy markup, in its Form Settings.

Gravity Forms has announced that legacy markup will be removed in a future version, after which every form uses modern markup. Gravity Forms 3.0 also changed several things that themes and code snippets often depend on: the submit, next and previous buttons are now <button> elements instead of <input> elements, the date picker is a new accessible library that no longer uses jQuery UI, the spinner filters were removed, and the gform_price_change event is on its way out. None of this is a problem for a form that was built recently. It is a problem for an older form whose look depends on CSS written for the old list markup, or for a site whose theme hooks into a filter that no longer runs.

Switching a form is one toggle. The hard part is knowing in advance what that toggle will change on your site, and being able to go back if something looks wrong. That is what this add-on is for.

What you need

You need Gravity Forms 2.9 or newer and WordPress 6.5 or newer on PHP 7.4 or newer. The add-on was tested with Gravity Forms 3.1 and with Gravity Forms 2.9. Everything runs inside your own WordPress: the add-on makes no outside connection apart from the usual GravityExtra licence and update checks.

Install and activate

  • Upload the add-on zip in Plugins → Add New → Upload Plugin and activate it.
  • Go to Forms → Settings → Markup Migration, enter your GravityExtra licence key and press Activate License.
  • The add-on page is under Forms → Markup Migration, with three tabs: Forms, Theme & code scan and Backups.

Without an active licence the page shows a short note and every action is refused. Your forms are not affected either way.

How it differs from other tools

Several of our add-ons work on forms as a whole, and each answers a different question. Our GravityMigrate add-on moves forms and their entries from other WordPress form plugins into Gravity Forms; the Markup Migration Assistant works on forms that are already Gravity Forms forms and moves them from legacy to modern markup. Our CSS Ready Class Picker gives the Custom CSS Class setting of each field a visual picker with labels and previews; the Markup Migration Assistant uses the same class list to replace the old layout classes with the modern layout settings, form by form, in bulk. Form Health checks the configuration of your forms for mistakes such as a notification without a recipient. Find & Replace changes text across your forms. Form Sync and Form Blueprint copy forms between sites or from templates.

Gravity Forms itself has the Enable legacy markup toggle on each form, and it shows a notice when a form still uses Ready Classes. It does not scan your theme or snippets, does not convert the classes for you, and has no rollback: in Gravity Forms 3.1 the toggle is only shown while a form still uses legacy markup, so after you switch it off in Form Settings you cannot switch it back on there. The Markup Migration Assistant adds the scan, the conversion, the preview, the dry run, the bulk switch and the rollback around that one setting.

Step 1: the Forms tab

The Forms tab lists every form on the site (active and inactive, not those in the trash) with its markup: Legacy or Modern. For each form you see the Ready Classes it uses, at field level and in the form’s own CSS class setting, and how many changes the switch would make automatically and how many classes need a look by hand. The tiles at the top count the forms, the forms on legacy markup, the classes the switch converts and the classes to look at.

Forms, Markup Migration: the forms with legacy or modern markup, the Ready Classes each form uses and what the switch will change, with a dry run and a bulk switch
The Forms tab: which forms still use legacy markup, their Ready Classes and what the switch will do.

If a form is marked forced on by a filter, a gform_enable_legacy_markup filter in your theme or a plugin turns legacy markup on for that form whatever its setting says. Switching that form would change the stored setting but not what visitors see; remove the filter first. The scan shows you where it is.

Step 2: the readiness scan (read-only)

Open Theme & code scan and press Run the scan. The scan reads:

  • the active theme, and its parent theme when the active theme is a child theme: CSS, Sass and Less files, JavaScript files, PHP files and HTML templates;
  • the must-use plugins folder, a common home for small code snippets;
  • the Additional CSS of the active theme (Appearance → Customize → Additional CSS);
  • the CSS classes of every form and field, and which forms still use legacy markup.

Folders such as node_modules and vendor are skipped, as are very large files. A developer can add more folders to the scan with the gfmarkupmigrate_scan_paths filter.

The read-only theme and code scan: findings in the child theme, its parent, a code snippet, the Additional CSS and the form classes, each with file and line, severity and a suggested modern equivalent
The read-only scan lists what would break, by file and line, with a severity and a suggestion. It never edits your files.

The scan is strictly read-only. It lists and reads files and never writes to a theme file, a child theme file, a snippet or your Additional CSS. You decide what to change, in your own editor or with your developer. In our tests every theme file, the snippet file and the Additional CSS were byte-identical (same SHA-256 checksum, same modification time) before and after the scan and after switching and rolling back forms.

Reading the findings

Each finding has a location (the file relative to wp-content and the line, or the form and field), what was found with a short excerpt, and what to do. Findings are sorted by severity:

  • High: will break. Code that relies on something Gravity Forms 3.0 removed or replaced, so it already does nothing on a current Gravity Forms: the gform_ajax_spinner_url, gform_spinner_url and gform_always_show_spinner filters, the gform_input_mask_script filter, jQuery UI date picker calls such as .datepicker(), selectors for the old submit input, a filter that forces legacy markup on, and the forms that still use legacy markup.
  • Medium: stops matching after the switch. CSS or scripts written for legacy markup: selectors such as ul.gform_fields, li.gfield, .gfield_checkbox li, h3.gform_title or .validation_error, styles for layout Ready Classes, jQuery UI date picker styles, the gform_price_change event and gform_submit_button filters. Also the Ready Classes on your fields that the switch converts, and those without a modern setting.
  • Low: deprecated, review. Things that still work today but are deprecated: the GFMergeTag script object, the date picker options filter, and Ready Classes such as the alert colours that Gravity Forms still styles.

Every rule comes with a suggested modern equivalent. For example, a selector on input.gform_button becomes .gform_button or button.gform_button; a ul.gform_fields li.gfield rule becomes .gform_fields .gfield; a gform_price_change listener becomes a listener on the gform/products/product_field_changed event. The rules were built from the Gravity Forms source code and change log, not from memory.

Step 3: the class conversion

Ready Classes were the way to lay out a legacy form. Modern markup has settings for the same things, and the converter applies them:

  • Column classes (gf_left_half, gf_right_half, gf_left_third, gf_middle_third, gf_right_third and the four quarter classes) become a row in the modern layout: the fields of one legacy row share a row and get a width of 6, 4 or 3 of the 12 grid columns. A row that is not full, such as a lone left half, keeps its empty space, as the form editor does. The class is then removed from the field.
  • Choice list classes (gf_list_2col to gf_list_5col, their _vertical versions and gf_list_inline) on checkbox, radio and multiple choice fields become the choice layout settings: columns, the number of columns, and whether choices fill across or down. These settings exist from Gravity Forms 2.9.16; on an older Gravity Forms the class is kept and listed.
  • Classes without a modern setting are never guessed. gf_inline and the gf_list_height classes are kept and listed “by hand” with a suggestion; classes that Gravity Forms still styles today, such as the alert colours, gf_scroll_text or gf_invisible, are kept and listed for review.

Your own classes on a field stay as they are, in the same order. Nothing else in the form changes: not the labels, the choices, the notifications, the confirmations or the feeds.

Credit: the class list, the column positions and the groups come from the class catalog of our own CSS Ready Class Picker add-on. The data is copied into this add-on with attribution (it is not read at run time), so the Markup Migration Assistant works whether or not the Ready Class Picker is installed. The modern equivalents follow Gravity Forms’ own mapping of the column classes to its width helpers.

Step 4: the side-by-side preview

On the Forms tab, press Side-by-side preview next to a form. Both sides are rendered by Gravity Forms itself from the saved form: the left side with legacy markup, the right side with modern markup and the converted layout. The conversion is applied in memory for the preview only; nothing is saved. Below the preview you see the list of changes.

The side-by-side preview of one form: on the left with legacy markup, on the right with modern markup and the converted column layout, and the list of changes
One form, side by side: legacy markup now, modern markup after the switch. Nothing is saved.

The preview uses Gravity Forms’ own form preview page, with your theme’s form styles. It shows the form markup and layout; it does not show your whole page, so look at the real page after switching too.

Step 5: the dry run

Select one or more forms on the Forms tab and press Dry run: show the changes. For each form you get a table of every change (legacy markup off, each converted row and choice layout) and a table of the classes that are kept, with the suggestion for each. A dry run writes nothing: no form setting, no backup, no form revision.

Step 6: the bulk switch

When you are ready, select the forms and press Switch selected forms to modern markup (on the Forms tab or at the bottom of the dry run). For each selected form the add-on:

  1. saves a backup: the complete stored settings of the form (the whole form settings row, including its confirmations and notifications) with the date and a SHA-256 checksum, in the add-on’s own table;
  2. turns legacy markup off and applies the class conversion;
  3. moves on to the next form. A form that already uses modern markup is skipped and left as it is.

The switch is atomic. It takes a site-wide lock with a single database update before it starts, so a double click, a reload or two administrators pressing the button at the same time give one backup and one change, never two. In our tests, two requests sent at the same moment produced exactly one backup and one write of the form; the second request changed nothing.

Step 7: backups and rollback

The Backups tab after a bulk switch: the batch with its date, each form with its timestamped backup and checksum, and the buttons to roll back one form or the whole batch
Each switch keeps a timestamped backup of every form it changed, with one-click rollback per form or per batch.

The Backups tab groups the backups by switch (batch), newest first, with the date, the forms, the number of changes and the status. Press Roll back on a form, or Roll back this batch for every form of a switch. Rollback writes the saved settings back exactly as they were and checks the checksum: in our tests the restored settings were byte-identical to the original, column by column.

If a form was edited after the switch, the rollback of that form is held back and the form is named, because rolling back would also undo those later edits. Press Roll back anyway if that is what you want.

Backups stay until you delete them. You can download all backups, or one batch, as a JSON file. Uninstalling the add-on removes its backups table, so download the backups first if you may want to roll back later. Uninstalling never changes your forms: forms you switched stay on modern markup.

Who can do what

  • The page (lists, scan results, backups list, dry run, preview) needs the Gravity Forms capability gravityforms_edit_forms.
  • Switching, rolling back, running the scan, downloading and deleting backups need a stricter capability: manage_options (administrators) by default. Developers can change it with the gfmarkupmigrate_bulk_capability filter.
  • Every action is protected by a WordPress nonce. A user without the capability is refused even with a valid nonce, and visitors see nothing of the add-on.

Notes for Gravity Forms 2.9

On Gravity Forms 2.9 the Enable legacy markup setting is shown in a different way (it depends on when the site was first set up and on whether any form uses legacy markup), and the choice layout settings arrive in 2.9.16. The add-on does not rely on either: it reads and writes the form settings directly through Gravity Forms, so the scan, the switch and the rollback work the same way, and list classes are kept on versions without the choice layout settings.

A sensible order of work

  1. Run the scan and fix the high findings in your theme or snippets (or ask your developer to).
  2. Rewrite the medium CSS findings so they target modern markup; most of them are a one-word change.
  3. Open the preview of your busiest forms, then run a dry run.
  4. Switch a few forms, look at the real pages, then switch the rest. Roll back any form that needs more work.

What the add-on does not do

  • It never edits your theme, child theme, snippets or Additional CSS. It tells you where to look and what to change.
  • It does not judge how a page looks. Check the switched forms on their real pages, especially forms with custom styling.
  • It cannot know about CSS or code in places it does not read, such as a page builder’s own style settings or a regular plugin’s files. Use the scan path filter for extra folders.
  • It does not change entries, feeds, notifications or confirmations.

Privacy and data

The add-on stores the backups of the forms you switch (form settings only, never entries), the result of the last scan (file paths, line numbers and short excerpts) and its own options. It makes no outside connection. Uninstalling removes its options, its lock, the last scan and the backups table.

Still need help?

Our support team answers tickets every day, usually within a few hours.

0
0
Your Cart
Your cart is emptyReturn to Shop
🔥 FREQUENTLY BOUGHT TOGETHER
Complete Combo & Save 40%!
ITEM IN YOUR CART
Gravity Forms Klaviyo Add-on
$39.00/yr
+
🎁 RECOMMENDED ADD-ON SAVE 40% OFF
Original Price: $39.00/yr
Bundle Special Price: $23.40/yr