Contextual Related Posts v4.4.0: Experimental WPBakery, Elementor and Bricks support

For years, the answer to “how do I add related posts to my page builder layout?” was the same: drop in the [crp] shortcode and preview the output on the frontend. That works, but it means no settings UI, no live preview, and no way for a client to change the number of posts without editing a shortcode string. Contextual Related Posts has supported the block editor for over 5 years. With v4.4, Contextual Related Posts Pro brings preliminary support to WPBakeryOpens in a new window, ElementorOpens in a new window, and BricksOpens in a new window.

Three page builders, natively

Contextual Related Posts Pro now ships a native Related Posts (CRP) element or widget for three builders, each carrying the full set of CRP options rather than a token subset.

I’m shipping all three as experimental. The code is tested and safe to run on a live site, but page builders are large, opinionated pieces of software, and I’ve tested against the versions I have rather than every combination of builder, theme, and template you might be running. Experimental means I expect to change things based on what comes back.

WPBakery Page Builder gets an element that works in both Classic Mode and the Frontend Editor. Elementor gets a widget with the same option set. Bricks Builder gets an element with the same options, and its free-text controls run through Bricks’ dynamic data parser, so you can feed them values from the rest of your Bricks setup.

Behind all three is a new Builders\Builders dispatcher. Each integration registers itself through it and checks whether its own builder is active before doing anything, which means adding Divi and Beaver Builder later is a matter of writing one class, not rewiring the plugin. The page builder integrations documentation covers the controls each one exposes.

Building any of this needed a working copy of the builder itself, and two teams handed me one. Thanks to the WPBakery team and the Bricks Builder team for giving me access to versions I could develop and test against. Neither of them had to do that, and without it these integrations would still be on the someday list.

A setting label that finally tells the truth

Include only posts that contain these words is now Also match posts that contain these words.

The rename isn’t cosmetic. That option has never restricted the related posts list. It widens the contextual match and ranks the matching posts higher. The old label described the exact opposite of what the code does, which is a great way to have people file bug reports against behavior that was working correctly.

Exclude words now work site-wide

Exclude posts that contain these words was only ever honored per post, through the Exclude terms field in the metabox. Setting it globally in the settings did nothing. It is now merged with the per-post value before the query runs, which is what everyone reasonably assumed it did.

Two related changes came with it. Exclude terms now split on commas only, so entering black friday excludes posts containing that phrase rather than every post mentioning the color or the day. And the exclusion is always checked against post_content, not just the title and excerpt. Previously, turning on content matching quietly dropped content from the exclusion check, so a post could be excluded on one site and not another depending on an unrelated setting. Both fields are documented in the List tuning settings reference.

Bug fixes

Cached output was leaking between calls. In Pro, two differently-configured CRP calls on the same post, a shortcode and a widget for example, could collide on the same cache key, so one call’s rendered HTML was silently served in place of the other’s. The cache key now retains every argument that affects the rendered output. Add page builder elements into that mix and the problem only gets wider, so we had to fix this before the builder work could ship.

Order by: Date wasn’t ordering by date. When the match SQL was empty, a strpos() check returned 0 and overwrote the first ORDER BY clause with relevance ordering. The same code path threw an Unknown column 'score' database error when contextual matching was disabled while Include words was set.

Stopwords stopped being stripped. If your translated stopword list or anything hooked to wp_search_stopwords contained a /, the pattern delimiter was left unescaped, preg_replace() returned null, and every stopword stayed in place, quietly degrading match quality.

Style stylesheets ignored the requested style. Only the site-wide default style’s CSS was ever enqueued, so a

shortcode with an explicit style, or a builder element set to a non-default style, rendered without its stylesheet. The handler now scans post content and builder element settings for every style actually in use.

Other fixes in this release:

• orderby="relevance" sorted by the unweighted core match instead of the Pro weighted relevance score.
• Sort by number of matching taxonomy terms was appended after the date sort instead of spliced in ahead of it.
• The contextual match SQL was being built twice on every related posts query. It is now built once and reused.
• HTML entities survived tag stripping, so & and   were indexed as the words “amp” and “nbsp”.
• On multisite, the per-request post meta cache was keyed on post ID alone, so the same post ID on two sites shared one entry.
• Schema changes now reach existing installs, because dbDelta() runs on version upgrades rather than on activation only.

What free users get

Everything genuinely new here is Pro. Free gets the label rename, the exclude words fixes, the stopword fix, the stylesheet fix, and the duplicated SQL fix. If you’re on free and don’t use a page builder, this is a quiet maintenance release. If you’re on Pro and you order by date, you’ll notice it the moment you update.

Tell me what breaks

This is the part where I need you. If you use WPBakery, Elementor, or Bricks, install the element, put it on a real page in a real template, and tell me what happens. What I most want to hear about: options that don’t take effect, styles that load in the editor but not on the front end, conflicts with your theme’s builder templates, and anything that looks right in the preview and wrong when published.

Bug reports go on GitHubOpens in a new window. Tell me which builder, which version, and what you expected to see. I’ll remove the experimental label once I’ve heard from enough real sites.

What’s next

Divi and Beaver Builder, through the same dispatcher.

The builders are the point of this release, and they were only possible once the caching and ordering underneath them behaved.