Savvy
Posts Grid

1.1Live Demo

The panel below runs on a loop: a query is typed out, the filter drawer opens, a category is picked, and the results settle. Nothing here talks to a server — it is a scripted mock of the real interaction, included so you can see the rhythm before installing anything.

1.2 Overview

Most post-grid widgets stop at "show me ten posts in three columns". This one is built for the archive that has to carry a real content library: tens of thousands of entries, a dozen ways to narrow them down, and an editor who wants the card to look like the rest of the site. Posts, pages and custom post types all render the same way.

1.3 Requirements

1.4 Installation

1. Put the files in placeDrop the savvy-posts-grid folder into /wp-content/plugins/, or hand the ZIP to Plugins → Add New → Upload Plugin.
2. Switch it onActivate from the Plugins screen. Boot happens on plugins_loaded; if PHP or Elementor is too old you get an admin notice rather than a fatal error.
3. Find the widgetOpen any page in Elementor and type "savvy" into the widget search. It also has its own category in the panel.
4. Optional — design the cardBuild a layout under Templates → Saved Templates, then choose it in the widget's Card Template section. Skip this and the built-in card is used instead.

Activation & deactivation behavior

• Activation stores spgrid_version for future migrations and flushes rewrite rules.
• Deactivation flushes all plugin transients via CacheManager::flush_all().
• Uninstall removes the spgrid_version and spgrid_cache_generation options and every spgrid_* transient (multisite-aware). Widget settings stored in Elementor documents are preserved so re-activation restores everything.

1.5 Quick Start

Six steps, and none of them involve leaving the Elementor editor.

1. Place itDrag Savvy Posts Grid into whichever section should hold the archive.
2. Say what to showUnder Query, pick a source — a custom query, a hand-picked set, posts related to the current one, or sticky posts — then the post types, how many per page, and the sort order.
3. Shape the gridLayout holds the mode (Grid, List or Masonry) plus column count and gap, each settable per breakpoint.
4. Add the filtersEach row in Filters is one control: choose what it filters on, how it should look, and whether multiple selections narrow or widen the result.
5. Check search and pagingBoth arrive switched on. The only decision is which of the three paging styles suits the page.
6. Make it yoursThe Style tab exposes typography, colour, spacing and border for every part of the widget.

2.1 Query

Everything that decides which posts land in the grid lives here. Worth knowing up front: when an AJAX request arrives, the server ignores whatever the browser claims these settings are and re-reads them from the saved Elementor document.

Sources

Controls

2.2 Layout

Three arrangements, each with its own column and gap values per breakpoint. Grid is the even-height default; List puts the image alongside the text; Masonry lets cards keep their natural heights and flow into columns.

2.3 Search & Heading

Search

The field waits 300 ms after you stop typing before it queries, so a fast typist produces one request rather than ten. Each new keystroke aborts whatever request is still in flight. Searching drops you back to page one but leaves your filters untouched.

Heading

2.4 Pagination

Pick whichever suits the archive. All three fetch over AJAX and carry the current search term and filter selection with them.

2.5 Filters & Filter Builder

Filters live in a drawer rather than a sidebar, so the grid keeps the page width. You describe each one as a row in a repeater; on the server those rows are folded into a single tax_query and meta_query rather than one query per filter.

Panel controls

The spgrid_filters repeater

One row becomes one collapsible group in the drawer. A Category row is present by default, so a freshly dropped widget already has a working filter — the toolbar's filter button only appears once at least one row exists.

Native filter sources

• Taxonomies — every public taxonomy (category, post_tag, customs…), keyed by taxonomy name.
• author — all published authors.
• date — month buckets (YYYYMM) covering the last 24 months.
• date_range — From/To date inputs for a published-date range.
• post_type — filter across the widget's selected post types.

Panel UX behavior

• Open / close — toggle button opens the panel (is-open class); close via the ✕ button, overlay click, or Escape. Background scrolling is locked with body.spgrid-noscroll.
• Accordion sections — each filter group collapses/expands (is-collapsed, with aria-expanded).
• Adding is batched, removing is not — ticking boxes does nothing until Apply is pressed, so a visitor can assemble a selection without the grid thrashing. Unticking one, or dismissing a chip, takes effect immediately.
• Chips mirror the drawer — whatever is applied appears as a dismissible chip above the grid, and dismissing one unticks the matching control inside the panel.
• Reset — clears all inputs and reloads unfiltered results.

2.6 ACF Integration

Install ACF and its fields simply show up in the filter source list, prefixed acf: — acf:project_status, and so on. Nothing needs registering. The field's own type decides what the filter looks like and how it is matched, so a date picker becomes a range and a checkbox becomes a choice list.

Supported field types

Performance & freshness

• The ACF field map is cached for 1 hour in the spgrid_acf_fields_map_v2 transient.
• Distinct meta values (for text/number filters) are cached for 10 minutes per field (spgrid_acf_vals_{hash}).
• Caches flush automatically when field groups change (acf/update_field_group, trash, untrash, delete).

2.7 Card Templates

The built-in card is a starting point, not a ceiling. Design the card as a normal Elementor template, wire its text and images to dynamic tags, then point the widget at it — the template is repeated once per post with that post's data behind the tags.

How dynamic tags resolve

Before each card is rendered the loop context is made real: setup_postdata() runs, the global $post is swapped, and in_the_loop is set. Only then is the template rendered. The effect is that a dynamic tag behaves exactly as it would inside a Theme Builder loop — it has no way to tell the difference.

• A template's CSS is emitted once per request, not once per card — fifty posts do not mean fifty copies of the same rules.
• Cards that arrive by AJAX are handed back to Elementor's handler registry, so a carousel or lightbox inside your template still initialises on page four the same way it did on page one.

2.8 Built-in Card

Leave spgrid_template_id at 0 and you get the bundled card instead. Every part of it — image, title, meta, excerpt, custom fields, button — can be switched off or moved, which covers most archives without opening the template editor at all.

Display toggles

Custom fields on the card

Add rows to spgrid_card_acf_fields to surface field values on the card itself — they render between the excerpt and the Read More link. Each row is one value:

• When ACF is present the value goes through get_field(), so return formats are honoured and a relationship or user field prints a name rather than an ID. Anything array-shaped is joined with commas.
• Empty values drop out silently, and if every row is empty the list is not rendered at all — no stray bullet on posts that never filled the field in.
• Markup: .spgrid-card__acf > .spgrid-card__acf-item > .spgrid-card__acf-label + .spgrid-card__acf-value.

Element ordering

Every element carries a number, and the card sorts by it — spgrid_order_category, spgrid_order_author, spgrid_order_date, spgrid_order_title, spgrid_order_excerpt, spgrid_order_acf and spgrid_order_read_more. It is the CSS order property underneath, so moving the date above the title costs a number change and no markup.

Markup

<article class="spgrid-card">
  <div class="spgrid-card__body">
    <div class="spgrid-card__meta">
      <span class="spgrid-card__author">
        <span class="spgrid-card__author-prefix">By</span> <a href="…">Author Name</a>
      </span>
      <time class="spgrid-card__date">06.05.26</time>
    </div>
    <h3 class="spgrid-card__title"><a href="…">Post Title</a></h3>
    <p class="spgrid-card__excerpt">Excerpt text…</p>
    <ul class="spgrid-card__acf">
      <li class="spgrid-card__acf-item">
        <span class="spgrid-card__acf-label">Location:</span>
        <span class="spgrid-card__acf-value">Lahore</span>
      </li>
    </ul>
    <a class="spgrid-card__more" href="…">Read More →</a>
  </div>
  <div class="spgrid-card__thumb">
    <a class="spgrid-card__thumb-link" href="…" tabindex="-1" aria-hidden="true">
      <img src="…" alt="…" loading="lazy">
    </a>
    <span class="spgrid-card__terms spgrid-card__terms--badge">
      <a href="…">Category</a><span class="spgrid-card__sep">|</span><a href="…">Category</a>
    </span>
  </div>
</article>

Theme override

Copy templates/card-default.php from the plugin into your theme as yourtheme/spgrid/card.php to fully customize the built-in card markup.

2.9 Style Controls

Every visual aspect is controllable from Elementor's Style tab.

Style sections at a glance

Key control IDs

3.1 AJAX API

Search, filtering and paging are all the same call. One endpoint is registered twice — wp_ajax_spgrid_query for signed-in users and wp_ajax_nopriv_spgrid_query for everyone else — and it returns rendered HTML rather than raw posts, so the card design stays on the server.

Request

action:    'spgrid_query'
nonce:     // CSRF token, verified against 'spgrid_nonce'
post_id:   // int — the page/document containing the widget
widget_id: // string — the Elementor element ID
search:    // string — search term
paged:     // int ≥ 1 — page number
filters:   // object — filters[filter_key][] = value…

Response

{
  "success": true,
  "data": {
    "html":        "<div class=\"spgrid-grid__item\">…</div>…",
    "empty_html":  "<p class=\"spgrid-empty\">No posts found.</p>",
    "pagination":  "<ul class=\"spgrid-pagination__list\">…",
    "has_more":    false,   // load_more / infinite only
    "total_pages": 3,       // numbered only
    "current":     1,
    "found":       27,      // numbered only
    "is_empty":    false,
    "cached":      false    // true when served from transient cache
  }
}

Important properties

• The request cannot widen the query. Settings are read back out of the saved Elementor document, so editing post_type or per_page in the payload changes nothing.
• Only declared filters are honoured. Keys that the widget did not define are discarded before the query is built, which closes the door on arbitrary meta lookups.
• A valid nonce is mandatory. Anything else gets a 403 and no query runs.
• Repeat requests are served from cache (see Caching). The cached flag in the payload tells you which happened.

3.2 Hooks & Filters

Five extension points, all namespaced under spgrid/. Between them you can reshape any query, swap the fallback thumbnail, and decide whether and for how long a result is cached.

Examples

add_filter( 'spgrid/query/args', function ( $args, $settings, $request ) {
    // Always hide the "internal" category from every grid.
    $args['category__not_in'][] = 42;
    return $args;
}, 10, 3 );

// Cache AJAX responses for 15 minutes instead of 5.
add_filter( 'spgrid/cache/expiry', fn() => 15 * MINUTE_IN_SECONDS );

// Disable caching entirely while developing.
add_filter( 'spgrid/cache/enabled', '__return_false' );

3.3 JavaScript API

The front-end script is plain JavaScript with no jQuery dependency. It constructs one Grid object per .spgrid-wrap on the page, each holding its own search, paged and filters state — so two grids on the same page never interfere with one another.

Localized config (SPGRID_CONFIG)

{
  ajaxUrl:  "https://yoursite.com/wp-admin/admin-ajax.php",
  nonce:    "…",            // wp_create_nonce('spgrid_nonce')
  action:   "spgrid_query",
  debounce: 300,            // search debounce in ms
  i18n: {
    loading:   "Loading…",
    noResults: "No posts found.",
    error:     "Something went wrong…",
    loadMore:  "Load More"
  }
}

Behaviour

3.4 Caching

The same search, on the same filters, on the same page, should not cost a second query. Responses are stored under a namespaced transient key; invalidation works by moving the namespace rather than hunting down individual entries.

Key structure

spgrid_{group}_{generation}_{hash}
      │        │            └─ MD5 of the normalized (ksort'd) request args
      │        └─ incrementing generation counter (bumped on content changes)
      └─ logical group, e.g. "ajax"

The hash covers the document ID, the widget ID and the entire request state. If Polylang is running, the active language joins the key too, so translations never serve each other's cards.

Lifetimes & invalidation

• Invalidation is a counter, not a sweep. Publishing a post increments the generation, which orphans every old key at once and lets them expire quietly — no DELETE … LIKE across the options table on every save.
• To clear it by hand call \Spgrid\Cache\CacheManager::flush_all(). Deactivating the plugin does the same thing.
• The editor is exempt. Nothing is cached in the Elementor editor or its preview, so a control change shows its effect immediately.
• Counting is skipped where it is pointless. Load More and infinite scroll never display a total, so the count query is turned off for them.

3.5 CSS Class Reference

These names are part of the plugin's contract and will not move between releases, so it is safe to hang your own CSS off them. The custom properties below are the cheaper hook where one exists — set the variable and every rule using it follows.

Structure

CSS custom properties

Accessibility

• The markup says what it is — <time> around dates, <nav> around pagination, <aside> for the drawer.
• The grid announces itself as a list, the drawer as a dialog, and state changes are carried by aria-busy, aria-expanded and aria-current so a screen reader hears results arrive.
• Escape closes the drawer, and every control in it is reachable by keyboard alone.

3.6 Security

The guiding assumption is that the request is hostile. Nothing the browser sends is allowed to decide what gets queried — it can only say which page, which search term, and which of the filters the widget already declared.

4.1 FAQ

4.2 Changelog

1.0.0

• Initial release — AJAX search, AJAX pagination (numbered / load more / infinite), off-canvas filter builder (native + ACF), Elementor template cards, and namespaced transient caching.
• Built-in card — toggleable, reorderable elements: image, title, meta, categories, author (linked or a custom static name with a configurable prefix), excerpt, ACF / custom-field rows, and Read More.
• Read More button controls — padding, border, border radius, background + border colors (normal/hover), and an Auto/Full-Width option, so the link can be styled as a real button.
• Identifiers — spgrid_ control prefix, Spgrid\ namespace, savvy-posts-grid text domain, spgrid-* CSS classes, spgrid_query AJAX action, and spgrid/* hooks.