Gravity Forms 3.1.1.1 adds the gform_addon_pages_using_components filter so an add-on can modify which pages use Gravity Forms components. A custom settings page can look correct in one admin route while loading duplicate scripts, missing localized data, exposing controls to the wrong role, or failing when the callback runs before another add-on.
Use this when maintaining a Gravity Forms add-on, private integration, custom admin page, white-label package, or agency toolkit that uses Gravity Forms components in wp-admin.
Quick answer
Build an inventory of every custom add-on page, its page key, required role, scripts, styles, localized objects, and component dependency. On staging, add one narrow filter callback and log its input and output. Test direct navigation, menu navigation, no forms, many forms, multisite, lower-privilege users, another add-on at an earlier priority, and the callback removed. Approve the change only when each intended page loads one compatible component bundle and every unrelated page keeps its original assets and permissions.
Test scenarios to run
Run the same controlled fixture across these branches. Write down the expected result before testing so a surprising response is easy to identify.
| Scenario | Fixture | Expected result |
|---|
| Target page | Valid page key | Components load once |
| Control page | Unlisted key | No added bundle |
| Low privilege | Direct URL | Access denied |
| Two callbacks | Different priorities | Stable final list |
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence | Verification |
|---|
| Inventory page keys and capabilities | Record Gravity Forms, WordPress, PHP, add-on versions, page keys, hook priorities, component names, script handles, style handles, localized objects, and required capabilities. | Every listed add-on page renders its controls without console, PHP, or missing dependency errors. |
| Add one narrow callback | Capture enqueued assets and console errors on each target and control page before adding the filter. | Unlisted Gravity Forms and WordPress pages do not receive unnecessary component assets. |
| Compare assets on target and control pages | Run callbacks that append, remove, reorder, duplicate, or return an invalid page key, then record how Gravity Forms handles the result. | Direct URLs and multisite contexts enforce the same capabilities as menu navigation. |
| Test callback priority and failure cases | Test normal admin navigation, direct URLs, browser refresh, multisite network and site admin, translated dashboards, and lower-privilege accounts. | Two callbacks produce a deterministic unique page list across refreshes and languages. |
What to check first
- Record Gravity Forms, WordPress, PHP, add-on versions, page keys, hook priorities, component names, script handles, style handles, localized objects, and required capabilities.
- Capture enqueued assets and console errors on each target and control page before adding the filter.
- Run callbacks that append, remove, reorder, duplicate, or return an invalid page key, then record how Gravity Forms handles the result.
- Test normal admin navigation, direct URLs, browser refresh, multisite network and site admin, translated dashboards, and lower-privilege accounts.
- Remove the callback and confirm the old loading path, menus, permissions, forms, notices, and saved settings return without stale cached assets.
Field notes
- Write the pass condition before changing anything. A repeatable synthetic fixture makes the before and after comparison useful.
- Keep exact versions and UTC timestamps because scheduled jobs, caches, retries, and background processing can change the evidence.
- Check the public experience and the stored server-side result. Admin previews and isolated API calls do not prove the whole workflow.
- Repeat the test after the relevant cache, queue, scheduled action, webhook, and observation window has finished.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
add_filter( 'gform_addon_pages_using_components', function( $pages ) {
$pages[] = 'my-addon-settings';
return array_values( array_unique( $pages ) );
}, 10 );
// Log page keys and asset handles on staging before rollout.
Why this usually happens
- A callback uses a visible menu label instead of the internal page identifier.
- Two add-ons append the same page and enqueue a component bundle twice.
- A script dependency exists in the editor but is missing on a direct settings URL.
- The page renders controls before the normal Gravity Forms capability check runs.
Decision rule
Ship the callback only when target pages load the required components once, control pages remain unchanged, permissions hold on direct URLs, and removing the callback restores the previous behavior.
Production verification checklist
- Every listed add-on page renders its controls without console, PHP, or missing dependency errors.
- Unlisted Gravity Forms and WordPress pages do not receive unnecessary component assets.
- Direct URLs and multisite contexts enforce the same capabilities as menu navigation.
- Two callbacks produce a deterministic unique page list across refreshes and languages.
Safe fix order
Use a sequence that makes each result easy to prove. Stop when new evidence changes the scope or owner of the problem.
- Inventory page keys and capabilities
- Add one narrow callback
- Compare assets on target and control pages
- Test callback priority and failure cases
- Document removal and rollback
Mistakes to avoid
- Changing production before recording exact versions, UTC time, the affected fixture, current behavior, and a tested rollback point.
- Accepting one successful admin screen while the public page, stored record, API response, accessibility tree, queue, email, or downstream system remains unchecked.
- Testing only as an administrator instead of the role, browser, device, locale, network state, and failure path that a real customer reaches.
- Leaving broad credentials, debug logs, temporary filters, synthetic records, or recovery code active after verification.
Questions teams ask during testing
Should I test this on production?
Use production for read-only evidence first. Reproduce the change on staging with a current data shape, theme, extensions, cache, and browser mix. If a production canary is necessary, make it reversible, identifiable, monitored, and unable to charge a customer or expose personal data.
How do I rule out a cache artifact?
Record the origin response, purge only affected paths, and repeat in private and normal sessions. Compare stored data and server logs with the visible page. A cache hit is useful evidence only when you know which version it contains.
What belongs in the evidence packet?
Keep UTC time, exact versions, fixture ID, role, browser, expected result, actual result, relevant response or log lines, change made, rollback point, owner, and final verification. Redact passwords, tokens, personal data, and private URLs.
When is the test complete?
Close it when the main path and important failure branches pass, records reconcile across systems, accessibility and mobile checks are complete, temporary changes are removed, and monitoring covers the next update or business cycle.
What to tell the client or owner
Give the owner a short packet with the affected workflow, exact versions, UTC test time, fixture ID, expected result, actual result, key evidence, change made, rollback point, unresolved risk, owner, and next review date. Remove credentials and personal data before sharing it.
When HandL WP should help
Bring in help when this affects leads, checkout, search visibility, security, paid media reporting, or a client production site. HandL WP can trace the issue through WordPress, hosting, cache, tracking, and Search Console, then verify the workflow after the technical fix.
If this is active on a production site, have HandL WP test a Gravity Forms add-on.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references