Alphabetical Pagination

2.3.0 feature surface

• Gutenberg block — server-rendered wp-snap-ext/index block (no JS build pipeline required). Renders identically to the shortcode + template tag.
• WooCommerce auto-mount — toggle in Settings → Alphabetical Pagination → WooCommerce . Mount hook selectable: woocommerce_before_shop_loop (default), woocommerce_archive_description , or woocommerce_before_main_content .
• REST API endpoints — /wp-json/wp-snap-ext/v1/letters returns [{ letter, count, href }] ; /wp-json/wp-snap-ext/v1/posts returns paginated post payloads.
• Developer hooks : do_action( 'wp_snap_ext/before_render', $context )
• apply_filters( 'wp_snap_ext/pre_render', $html, $post_type, $display, $args ) — short-circuit
• apply_filters( 'wp_snap_ext/query_args', $args, $context )
• apply_filters( 'wp_snap_ext/letter_href', $href, $letter, $base )
• apply_filters( 'wp_snap_ext/excerpt', $excerpt, $post_id )
• apply_filters( 'wp_snap_ext/render', $html, $post_type, $display, $args )
• do_action( 'wp_snap_ext/after_render', $html, $context )

Transient letter-availability cache — keyed by post_type, taxonomy, term, current language, alphabet pack, and menumisc setting. Invalidated on save_post , deleted_post , trashed_post , untrashed_post , and switch_blog . Default TTL 1 hour, configurable. WPML + Polylang awareness — cache key includes wpml_current_language or pll_current_language() ; WP_Query runs with suppress_filters => false so translated post sets get filtered. 15 multi-language alphabet packs — pick a script from the dropdown, the freeform Local Alphabet field is overwritten on save. Appearance toggles — Horizontal / Vertical layout, Uppercase / Lowercase letter case, Disable Empty Letters (renders empty buckets as muted + aria-disabled ), Hide Pagination If One Page. Generic taxonomy filter — restrict the index to any registered taxonomy + term (beyond the legacy cat/tag args). Meta-key intra-bucket sorting — set a post meta key + ASC / DESC to override post_title ordering within each letter bucket. Buckets still derive from post_title. Per-page override map — { post_id => items_per_page } so /glossary can render 50 items per page while /products renders 20. DOM auto-injection — for themes that don’t expose a hook: render the index in the footer and move it into a CSS selector via ~300 bytes of vanilla JS. No jQuery.

Backwards compatibility

• The legacy wp_snap() template tag is preserved as a thin alias.
• Legacy URL parameters ?snap= , ?cp= , and ?snap_paged= continue to be honoured alongside the canonical ?alpha_order= and ?alpha_paged= .
• Legacy key_snap_* option keys are migrated to wp_snap_ext_* automatically on activation.

Usage

Gutenberg block

Add the Alphabetical Pagination block from the block inserter (Widgets category) and configure attributes through the block sidebar:

• postType — post type to index (default post ).
• menu — 1 , 2 , or 3 (see menu styles in the admin panel).
• firstload — all , none , or recent .
• category — category ID or all .
• includeChildren — include category children.
• taxonomy + term — restrict the index to a specific term of any registered taxonomy.
• display — true (default) renders the post list under the letter nav; false renders only the letter nav.

The block is fully server-rendered — its HTML matches the shortcode and template tag output byte for byte, and there is no JS build pipeline behind it.

Shortcode

Drop the shortcode into any post, page, widget, or Site Editor template part:

[alphabetical_pagination]

All template-tag arguments are exposed as shortcode attributes:

[alphabetical_pagination cat="15" child="true" menu="2" firstload="recent" post_type="post" display="true"]

Attribute reference:

• cat — category ID, or all .
• child — true to include category children (default false ).
• menu — 1, 2 or 3 (see menu styles in the admin panel).
• firstload — all , none or recent .
• post_parent — restrict to posts with a given parent ID.
• post_type — defaults to post . Whitelisted against registered post types.
• display — true (default) renders the post list under the letter nav; false renders only the letter nav.

The shortcode handler buffers its output through ob_start() / ob_get_clean() , so the index renders exactly where you place the shortcode rather than breaking out of the surrounding layout.

Theme template tag

For deeper theme integration, call alphabetical_pagination() directly from a template file. The legacy wp_snap() name is retained as a backwards-compatible alias.

<?php if ( function_exists( 'alphabetical_pagination' ) ) { echo alphabetical_pagination(); } ?>

Passing arguments works the same as the original wp_snap() API:

<?php echo alphabetical_pagination( 'cat=15&child=true&firstload=recent' ); ?>

Render an alphabetical index over a custom post type:

<?php echo alphabetical_pagination( '', 'glossary_term' ); ?>

Render only the letter navigation (without the post list):

<?php echo alphabetical_pagination( '', 'post', false ); ?>

URL query parameters

Once embedded, the plugin reads two query parameters on the front end:

• ?alpha_order=A — the active letter (or bucket, like A-D ). alpha_order=misc selects the # bucket of non-alphanumeric titles.
• ?alpha_paged=2 — the active pagination page.

These are isolated to the plugin (they do not collide with WordPress’s own paged / tag / cat query vars). The legacy ?snap= / ?cp= parameters from earlier versions are still accepted so existing bookmarks keep working.

Gutenberg block attributes

Attribute Type Default Notes

postType string post Any registered public post type.

menu number 1 1, 2, or 3.

firstload string recent all / none / recent .

category string “ Category ID or all .

includeChildren boolean false Include category children.

taxonomy string “ Any registered taxonomy slug.

term number 0 Term ID for the taxonomy above.

display boolean true Render the post list under the nav.

The block supports wide and full alignment via the supports.align declaration in block.json .

REST API

Two read-only public routes under /wp-json/wp-snap-ext/v1/ :

GET /letters

Query params: post_type (default post ), taxonomy , term .

Response (200 OK):

[ { "letter": "A", "count": 12, "href": "https://example.com/?alpha_order=A" }, … ]

GET /posts

Query params: post_type , taxonomy , term , letter (single character or # ), page (default 1), per_page (default 10, max 100).

Response (200 OK):

{ "posts": [ { "id": 42, "title": "...", "permalink": "...", "excerpt": "..." } ], "total": 75, "total_pages": 8, "page": 1, "per_page": 10 }

Toggle the endpoints on / off under Settings → Alphabetical Pagination → REST API & Cache . Lockdown plugins that block public REST surface should leave the toggle off.

WooCommerce auto-mount

Enable Settings → Alphabetical Pagination → WooCommerce → Auto-mount on Shop . The index renders above the shop loop (or after the archive description / before main content — pick the mount hook from the dropdown) on:

• the WooCommerce shop archive,
• product taxonomy archives (e.g. /product-category/food ).

The mount uses native WooCommerce actions, never posts_where , so it does not collide with caching plugins, SEO plugins, or multilingual plugins that also filter WP_Query.

Developer hooks

Customise behaviour without forking through the following hooks (added in 2.3.0):

add_filter( 'wp_snap_ext/query_args', function( $args, $context ) { $args['meta_query'] = [ [ 'key' => 'featured', 'value' => '1' ] ]; return $args; }, 10, 2 ); add_filter( 'wp_snap_ext/letter_href', function( $href, $letter, $base ) { return str_replace( '?alpha_order=', '#letter/', $href ); }, 10, 3 ); add_filter( 'wp_snap_ext/excerpt', function( $excerpt, $post_id ) { return wp_trim_words( $excerpt, 25, '…' ); }, 10, 2 );

Full list:

• do_action( 'wp_snap_ext/before_render', $context ) — fires before the index renders.
• apply_filters( 'wp_snap_ext/pre_render', $html, $post_type, $display, $args ) — short-circuit; return a string to replace the HTML.
• apply_filters( 'wp_snap_ext/query_args', $args, $context ) — mutate WP_Query