Woodmart Category Showcase

A dynamic Gutenberg block that renders a WooCommerce product category as a structured section — label, title, view-all link, child-category tabs, and a product grid — while delegating the product grid itself to Woodmart's native wd/products block so product cards stay visually identical to the rest of the site.

Core principle: the plugin owns the section structure. It does not emit a single line of product card markup. Card design stays Woodmart's responsibility, forever.

Status

v0.1.0 — scaffolded, with compiled build/ assets committed so the plugin can be uploaded and activated without running a local Node build. Not yet tested against a live Woodmart install.

Requirements

Install (normal upload-and-activate)

1. Download a release zip (or create one with npm run plugin-zip).
2. In WordPress admin: Plugins → Add New Plugin → Upload Plugin.
3. Upload zip and activate Woodmart Category Showcase.

No Node/npm is required on the production server if you're installing from the zip artifact because compiled build/ assets are included.

Install (development)

git clone https://github.com/onabhani/wd-cat-showcase.git
cd wd-cat-showcase
npm install
npm run build         # production build into ./build
npm run start         # dev watcher

Then symlink or copy the folder into wp-content/plugins/ and activate "Woodmart Category Showcase".

Architecture

Responsibility split

Plugin       → section wrapper, header, view-all, child-category nav, settings
Woodmart     → product grid + product cards (via wp:wd/products block)
WooCommerce  → product/term data
Theme        → typography, colors, card styling

Render flow

Gutenberg block (dynamic, save=null)
   │
   └─► PHP render_callback: Renderer::render()
          │
          ├─ sanitize attrs (absint, casts)
          ├─ validate categoryId in product_cat
          ├─ render_header()       ── label, title, view-all (fallbacks: term name, term link)
          ├─ render_children()     ── get_terms(parent), <nav> with anchor links
          └─ render_products_grid()
                 │
                 ├─ build <!-- wp:wd/products {…} --> comment
                 │   with `categoriesIds` = (string) categoryId
                 └─ do_blocks( $comment )   ← Woodmart renders the cards

File map

Naming conventions

• Block name: hdqah/wd-cat-showcase
• PHP namespace: Hdqah\WDCS
• Text domain: wd-cat-showcase
• CSS root class: .wdcs (all rules scoped under it — see style.scss)
• REST namespace: wdcs/v1
• Filter prefix: wdcs_

Unique block ID handling

Woodmart uses blockId for scoped CSS/behavior. To prevent collisions when multiple instances live on one page:

1. Editor: on first insert, crypto.randomUUID() generates wdcs-<uuid> and persists it to the block's blockId attribute.
2. Server: if blockId is empty (older saves), unique_block_id() falls back to a UUID at render time.
3. The Woodmart inner block receives wd-<blockId> to keep its namespace distinct from ours.

Dependency degradation

Block attributes

See block.json for the authoritative list. Highlights:

Extension points

/**
 * Mutate the attributes passed to the inner wd/products block.
 *
 * Use this to enable Woodmart options not exposed in the inspector
 * (carousel mode, custom hover, etc.).
 */
add_filter( 'wdcs_woodmart_products_attrs', function( array $wd_attrs, array $block_attrs ): array {
    $wd_attrs['products_view'] = 'carousel';
    return $wd_attrs;
}, 10, 2 );

Roadmap

License

GPL-2.0-or-later.