Migrate Finder content to Faceted Search

POM provides a WP-CLI command for converting stored legacy Finder shortcodes to the current Faceted Search elements. Use it only on a site that still contains Finder content.

The command converts supported stored content, creates corresponding Faceted Search contexts, enables the feature when changes are applied, and reindexes. It also reports references that still require review.

Prerequisites

• Current POM Theme code is active.
• WP-CLI can load the target WordPress site.
• A current database backup exists.
• You know the exact site URL in a multisite installation.
• The Finder pages and their expected behavior are documented for comparison.

Preview the migration

Run:

wp pom migrate-finder-to-faceted-search --dry-run --url=https://example.com

The preview reports replacements, generated contexts, warnings, and remaining stored Finder references without writing changes.

Resolve warnings that would make the result ambiguous. Use --fail-on-remaining when an automated or scripted check must exit unsuccessfully if warnings or stored references remain:

wp pom migrate-finder-to-faceted-search --dry-run --fail-on-remaining --url=https://example.com

Apply

After reviewing the dry run and backup:

wp pom migrate-finder-to-faceted-search --url=https://example.com

For multisite network options that intentionally contain Finder content, add --include-network-options.

An applied run prints a rollback run ID when replacements were made. Record that ID with the site and verification notes.

Verify the converted pages

1. Open the Faceted Search context list and inspect the generated contexts.
2. Wait for the reindex to complete.
3. Compare initial results with the former Finder page.
4. Test each converted filter, submit behavior, reset, sorting, pagination, maps, and responsive layout.
5. Search the site for remaining Finder references reported by the command.
6. Keep legacy components available until this review is complete.

Roll back a run

If verification fails and the stored values must be restored, use the recorded run ID:

wp pom migrate-finder-to-faceted-search --rollback=20260712-120000-abc123 --url=https://example.com

Rollback restores values recorded by that applied run. It does not replace the need for the pre-migration backup or undo unrelated edits made afterwards.