Post Inserter Block Customization
Post Inserter Block Customization
This guide covers advanced customization options for the Post Inserter Block, intended for administrators configuring newsletter templates and custom field integration.
ACF Fields in Newsletters
Custom fields created with ACF (see Create Custom Fields in Purple Hub) can be displayed in newsletter article teasers. Configuration happens in the Newsletter settings page (see Setup + Configuration).
Important: The ACF field's "Return Format" setting determines how the field data is accessed in templates:
- Image fields: Use "Image URL" or "Image Array" return format (not "Image ID")
- Text fields: Standard text return
- Toggle fields: Returns boolean values
Specific Date Filter
By default, the Post Inserter filters content by its publication date. The Specific Date Filter is an alternative mode where each piece of content carries its own validity period, and the newsletter pulls in everything that is valid on the day it is sent. This is useful for content with a fixed lifespan — such as ads, banners, or job listings — that should appear in newsletters only between a start and end date, regardless of when it was published.
The feature is enabled globally and is off by default.
Enabling the feature
On the post inserter settings page, set the Specific Date Filter dropdown to one of three modes:
- Off — the feature is disabled. No validity date fields are added to your content.
- Optional — the "Valid from" / "Valid until" date fields are added to all content types, and a "Use specific date filter" option is added to every Post Inserter block (see Post Inserter Block). Editors may leave either date field empty ("valid from the beginning" / "never expires").
- Required — same as Optional, but both date fields are mandatory: editors must fill in "Valid from" and "Valid until" before they can save affected content.
Switching from Off to Optional or Required automatically adds the date fields and the block option; switching back to Off removes them again.
Valid from / Valid until on content
While the feature is enabled, every post of every post-type shows a Newsletter validity period section with two date fields:
- Valid from — the first day the content may appear in a newsletter. Leave empty for "valid from the beginning".
- Valid until — the last day the content may appear. Leave empty for "never expires".
Content that has neither date set is never included by a Post Inserter that uses the specific date filter. Both fields also can be sortable columns in the post overview, so you can review validity at a glance (see Set Columns in Overview pages).
Priority Sorting
When the Specific Date Filter is enabled (Optional or Required), each article gains an extra numeric Priority field alongside the "Valid from" / "Valid until" fields. It lets editors manually order articles in a Post Inserter block without breaking the automated article feed — the live connection to the source content stays intact.
Setting a priority
The Priority field is optional and accepts any number. Lower numbers rank higher: an article with priority 1 appears first, followed by 2, 3, and so on in ascending order. Leaving the field empty means the article has no priority.
Sorting by priority
In the Post Inserter block, choosing Priority as the sort order arranges posts as follows:
- Prioritised posts come first, in ascending order (priority 1 first).
- Posts without a priority are listed after all prioritised posts.
- If several posts share the same priority — and among the unprioritised posts — the newest article is listed first.
The Priority sort option only appears in the block when the Specific Date Filter is enabled. Sorting by priority works together with the automated article selection, so editors do not need to manually insert or reorder articles.
Custom Template Blocks
Custom template blocks allow combining multiple ACF fields with HTML and conditional logic. These are configured in the Newsletter settings page and can be inserted into Post Inserter layouts.
Handlebars Syntax
Templates use Handlebars.js syntax to dynamically display content based on article metadata. See e.g. https://handlebarsjs.com/guide/builtin-helpers.html for guides on that language.
Basic ACF Field Display
Display a simple ACF field (e.g., an overline/dachzeile):
{{#if acf.overline}}
<h4>{{acf.overline}}</h4>
{{/if}}You can use any HTML tag: h1-h6, b, i, code, span style="color: blue", etc.
Using Gutenberg Block Syntax
For better compatibility with the WordPress editor, wrap content in Gutenberg block comments:
{{#if acf.dachzeile}}
<!-- wp:heading {"level":4} -->
<h4 class="wp-block-heading">{{acf.dachzeile}}</h4>
<!-- /wp:heading -->
{{/if}}Conditional Logic
Display content only when specific conditions are met.
Paywall badge example (shows badge only for premium articles):
{{#if acf.is_premium_article}}
<img src="https://example.com/badge-premium.png" alt="Premium content">
{{/if}}Combining Multiple Fields
Sponsored content example (combines sponsor image and URL):
Given an ACF field promoter_image (return format: URL) and a text field promoter_url:
{{#if acf.promoter_image}}
{{#if acf.promoter_url}}
<a href="{{acf.promoter_url}}">
{{/if}}
<img src="{{acf.promoter_image}}" style="width: 200px;" alt="">
{{#if acf.promoter_url}}
</a>
{{/if}}
{{/if}}This displays the sponsor image when available and makes it clickable if a URL is also provided.
Linking to the Article
Besides the ACF fields, the post itself is available in templates as the post object. Its most useful field is {{post.link}}, which contains the resolved public URL of the article — the same URL the built-in title link and the "continue reading" link point to, resolved through Purple (see URL Resolver) rather than the WordPress-internal URL. See also Frontend Links in Purple Hub.
<a href="{{post.link}}">{{post.title.rendered}}</a>Debug Helper
To see all available ACF fields and their values for testing, define a custom block with the following handlebars code and use it in a Post Inserter Block:
{{json acf}}The same works for the post object, to see all of its available fields:
{{json post}}Custom CSS
Custom CSS can be applied to inbuilt Post Inserter Blocks for advanced styling. The custom CSS editor in Newsletter settings supports either direct CSS rules or individual selectors. Often, these rules are conflicting with the default styles from the HUB or from the Newsletter styling, so adding !important is usually necessary.
Example: Change text styling for e.g. the post title via direct CSS rules:
font-family: monospace !important; text-decoration: none !important;Example: Style e.g. the continue reading link as a button via individual selectors:
a {
background: #080;
border-radius: 100px;
padding: 10px;
text-decoration: none !important;
}
a:hover {
background: #2a2;
}Note: Newsletter buttons use CSS only (no JavaScript), so all styling must be CSS-based.
"Continue Reading..." Label
The "Continue Reading..." block is a link to the article itself, and the label text of this link can be adjusted here, to e.g. be in german if your newsletters should be german.
Default excerpt length
The "excerpt" Post Inserter Block is set by default to include 15 words of a posts excerpt or content. This number can be changed here, so that new Post Inserter Blocks automatically have the number selected that you prefer.
Claude Code Instructions
You are helping manage newsletter templates in Purple Hub (WordPress/Gutenberg CMS).
Templates use Handlebars.js syntax. Key variables available in every template:
- post.title.rendered — post title
- post.excerpt.raw — post excerpt
- post.link — resolved public URL of the post (via Purple URL Resolver)
- post.id — post ID
- post.featuredImageMediumURL — featured image URL (plain string, not object)
- post.featuredImage.acf.[fieldname] — an ACF field set on the featured image itself (the attachment), e.g. post.featuredImage.acf.copyright. Editors set these on the image in the Media Library, not on the article. Access follows the same return-format rules as the article-level acf.fieldname fields below.
- post.featuredImage.[property] — the full featured-image media object, for when the URL-only variables above aren't enough. Useful properties: `source_url`, `alt_text`, `caption.rendered`, `title.rendered`.
- post.[taxonomy-slug] — boolean, true if post belongs to that taxonomy term.
Taxonomy slugs with hyphens must use bracket notation: post.[my-category]
- post.[taxonomy-slug].[0] — first term value of a taxonomy (plain string: name).
Example: post.[advertiser].[0]
- acf.* — ACF custom fields; access depends on the field's Return Format setting:
- Image field "Image URL" → {{acf.fieldname}} (plain string)
- Image field "Image Array" → {{acf.fieldname.url}}
- Text field → {{acf.fieldname}}
- Toggle field → boolean
Available taxonomies and ACF fields are project-specific and must be confirmed
per project. Use the debug helpers during development to inspect what is available:
- {{json acf}} — outputs all ACF fields and their current values
- {{json post}} — outputs all post fields and their current values
HTML structure:
Newsletters are rendered in email clients. Always use HTML tables for layout,
never CSS flexbox or grid. Use inline styles for all styling. The standard
pattern for a post block with an optional image is:
<table cellpadding="0" cellspacing="0" border="0" style="width: 100%;">
<tr>
<td style="width: 120px; vertical-align: top; padding-right: 24px;">
<!-- optional image -->
</td>
<td style="vertical-align: top;">
<!-- text content -->
</td>
</tr>
</table>
When the image cell is conditionally omitted, the text cell automatically
expands to full width — no colspan needed.
Known workaround: Post Inserter skips posts without a featured image unless the
template outputs something unconditionally. Fix: add a hidden row at the end of
every table: <tr style="display:none"><td>{{post.id}}</td></tr>
When there is no featured image, omit the image <td> entirely so the text <td>
uses full width. The hidden row ensures the post still renders regardless.
Global CSS handles link styling (color, font-weight, text-decoration) via the `a`
selector. Do not repeat these in inline styles on <a> tags — only keep font-family
inline. Global CSS uses !important, so inline styles without !important will lose.
Each newsletter layout has its own global CSS, so never hardcode brand colors in
templates.