Build a filterable listing inside a page

This workflow is for site owners building directories, portfolios or other structured listings with POM Theme and a connected MCP client. It works on a remote WordPress installation; the client only needs to send JSON and markup.

Enable MCP and Allow POM Theme writes in POM AI → Settings → MCP. Content and metadata creation also require Allow content writes. The connected user needs the relevant WordPress editing capabilities and manage_options for theme configuration. OAuth grants must cover every operation used.

1. Use pom_theme_configure_content_model to define the content types, taxonomies, custom fields and feed/single/archive templates. Use stable repeater_identifier values. Preview first, apply, then refresh discovery.
2. Create content with pom_site_save_content, terms with wp_create_term, term assignments with wp_add_post_terms, and values with wp_update_post_meta. Defining a field does not populate it.
3. Read pom_site_get_listing_catalog. Call pom_site_save_query with query_id, name, post_types and optional per_page, orderby, order. Preview, then apply with the returned revision. This creates or replaces one query and preserves the other queries.
4. Activate the faceted_search group with pom_theme_patch_settings, then refresh. The listing catalog now includes the saved query's context, named ctx_query_<query_id>, and registered facet types.
5. Use pom_site_save_facets with that context_id and a facets array. It replaces filters in that context and preserves other contexts. Preview first and apply at the returned revision.
6. Call pom_site_reindex_facets to start the native indexer. Inspect its result. If done is false, later calls advance one batch; WordPress scheduled jobs may also advance it. Stop when done is true. Starting another call after completion begins a new index.
7. Call pom_site_build_listing with query_id, feed_template, faceted: true and optional columns. Insert the returned content into a page using pom_site_save_content.
8. Generate theme assets, clear the site's POM Cache if available, and check the page in the browser. Verify initial results, a filter, text search, no results, reset, pagination, single-item links and mobile controls.

Content-model post-type rows use single_template_id, feed_template_id and archive_template_id for existing template identifiers, or their _key equivalents for templates created in the same request. Read pom_get_template_schema and pom://theme/content-model-guide for the exact supported properties. The listing builder's separate feed_template argument contains the selected feed template's identifier.

Saving a named custom stylesheet makes it available for assignment; it does not apply it everywhere. Assign it through the template's css_stylesheets, or use pom_theme_update_global_css for site-wide CSS. Activate the Custom CSS group and generate assets after saving.

Query inputs

Queries created here select published content from registered public post types. per_page is 1–100; ordering supports date, title, modified date or menu order, ascending or descending. Arbitrary SQL and query clauses are not accepted. Replacing a query replaces its parameters, including any earlier parameters configured elsewhere; review the preview carefully.

Filter inputs

Each facet requires id, label and a registered type. A search facet needs no source. Other facets need source with type and key. Supported source families are tax, meta, post and post_type. Public taxonomies must already exist. Protected and sensitive metadata is refused. Use indexed_meta_keys for metadata needed by a result template. Native POM normalization remains authoritative for ui options and facet behaviour.

{
  "context_id": "ctx_query_spaces",
  "facets": [
    {"id": "space_search", "label": "Search", "type": "search"},
    {"id": "space_type", "label": "Type", "type": "checkboxes",
     "source": {"type": "tax", "key": "space_type"}}
  ],
  "dry_run": true
}

The builder returns the existing web_listings shortcode, the selected feed template, matching facet controls, selections, counts, pager and reset. columns accepts 1, 2, 3, 4 or 6, with the theme's responsive defaults. It generates source; it does not save a page. Faceted output omits the ordinary pagination checkbox so the facet pager owns pagination; non-faceted output enables ordinary pagination. Validate the returned source inside its final builder layout before saving the page.

If results are empty, verify that items are published, the query selects the right post types, the context is enabled and indexing has completed. If custom fields are blank after filtering, check their indexed metadata declarations. For conflicts, read and preview again before applying.

Related: Typed settings, site plans, template assignment.