FastPixel Dynamic Fragments: How-To Guide

Fragments let you keep most of a page cached and optimized while refreshing selected dynamic sections, such as a rotating testimonial or a changing public announcement. Dynamic fragments are included in the FastPixel plugin; no separate installation is needed.

1. Mark the section to refresh #

Page-content fragments #

Add an HTML comment immediately before and after the dynamic section:

<!-- fp-fragment:customer_testimonial:start -->
<!-- Your existing dynamic content stays here, unchanged. -->
<!-- fp-fragment:customer_testimonial:end -->

Replace customer_testimonial with your fragment’s name. Keep your existing content, shortcode, or supported widget between the comments. The comments mark what to refresh; they do not make static text dynamic by themselves.

Do not add an extra <div> or other wrapper. Only add the opening and closing comments around the existing content. A fragment can contain one or several top-level elements; FastPixel applies the fade to those elements individually, together, without inserting a wrapper.

Use an HTML-capable editor block or your page’s HTML editing mode. The markers must appear as actual HTML comments in the rendered page, not visible text or an escaped code example. Visitors will not see the comments.

Follow these rules:

• Use exactly the same name in the opening and closing comments.
• Choose a name of 1-64 letters (a-z, A-Z), digits, underscores, or hyphens, such as daily_offer. Do not use spaces.
• Give each page-content fragment on a page a unique name.
• Both comments must share the same existing HTML parent. Do not put one inside a section and the other outside it; no new container is needed.
• Do not nest fragments inside other fragments.

Not every page builder or widget is supported, particularly content outside the page body, such as template headers and footers. Ask your site administrator to confirm compatibility if needed.

Save the page and refresh its FastPixel cache so the optimized version includes your markers.

Custom HTML widget fragments #

For content in a standard WordPress Custom HTML widget, use the separate widget markers inside that widget’s saved content:

<!-- fp-fragment-widget:testies_main:start -->
[ggshortcode_testies]
<!-- fp-fragment-widget:testies_main:end -->

Here testies_main is a fragment name you choose, not the widget title or the name of its widget area (such as “Home page”). Assign the widget to a registered, active widget area. The integration discovers which widget contains the markers; you do not need to add its internal ID or sidebar name. Moving it to another registered area does not require changing the markers.

Shortcodes work only if your site already enables them in Custom HTML widgets through their normal content filters. The integration does not add shortcode execution. Test that the unoptimized widget already renders correctly.

Widget fragment names must be unique across all eligible Custom HTML widgets on the site. A widget may contain several separate fragments. A page-content fragment and a widget fragment may use the same name, but fragments of either type must not be nested inside one another. Each widget fragment may appear only once on a rendered page.

Public-access opt-in: adding these markers makes that fragment available through the public widget endpoint while the widget is assigned to an eligible area. Do not mark private/member-only content or rely on the original page’s access controls or sidebar visibility rules to protect it. Inactive, unassigned, and unregistered-area widgets are not served.

This route renders only the selected widget, not the page or entire sidebar. It works on a blog/posts-index page too. Widgets that depend on the original page’s query, current post, or theme-template setup are not supported by this isolated rendering mechanism. Block widgets and arbitrary third-party widget types are not automatically supported.

The widget markers support the same fade-in, :clipping, and status behavior described below. Refresh affected FastPixel page caches after adding/changing markers or moving/removing a widget.

2. Choose how fresh content appears #

Default: fade in #

The example above uses fade-in automatically. You can also request it explicitly:

<!-- fp-fragment:customer_testimonial:start:fadein -->
<!-- Your existing dynamic content stays here, unchanged. -->
<!-- fp-fragment:customer_testimonial:end -->

When refreshing starts, FastPixel temporarily hides the cached section while keeping its layout space. Fresh content fades in over 350 milliseconds. If the refresh fails or takes longer than 5 seconds, the cached content is shown again.

The cached section may briefly appear before refreshing starts. Visitors who prefer reduced motion do not get the fade. The effect is also skipped when it would conflict with existing animations, styles, or unwrapped text.

For example, if the section already contains two sibling paragraphs, both fade together without a surrounding <div>:

<!-- fp-fragment:customer_testimonial:start -->
<p>Existing testimonial text.</p>
<p>Existing customer name.</p>
<!-- fp-fragment:customer_testimonial:end -->

Text directly between the markers but outside any element is still refreshed, but causes the fade effect to be skipped. Whitespace between elements is fine.

No fade: clipping #

Add :clipping to the opening comment only:

<!-- fp-fragment:customer_testimonial:start:clipping -->
<!-- Your existing dynamic content stays here, unchanged. -->
<!-- fp-fragment:customer_testimonial:end -->

This keeps the cached section visible while fresh content is requested, then replaces it without a fade. Despite its name, this option does not crop content. It does not use the default mode’s five-second timeout; cached content remains visible while waiting, or if the request fails.

Use clipping when keeping content visible matters more than temporarily showing an older version. Neither mode prevents layout shifts if the replacement has different dimensions.

3. How it works #

1. FastPixel serves the optimized page with a cached copy of the fragment.
2. The visitor’s browser automatically requests fresh content from your WordPress site, without waiting for a click or scroll.
3. Only the marked section is replaced. The rest of the page stays in place.

Each fragment refreshes independently, once per page load. This is not continuous live updating. If JavaScript is disabled, the cached content stays visible.

You do not need to enter an API URL: FastPixel uses the site’s advertised WordPress REST address, including supported subdirectory installations.

Tips and checking your setup #

• Mark only sections that need fresh content. Each fragment adds a request to your site; the main page can appear before dynamic content is ready.
• Keep replacement sizes reasonably consistent to reduce visible movement.
• Use public content suitable for caching as a fallback, not private account details or content that must never display an older value.
• Fragments refresh HTML and supported CSS, not JavaScript-driven widget initialization. Embedded scripts or separate asset tags in the returned content are not supported.

Open the optimized page and confirm the section refreshes. A fresh result may look identical if the underlying content has not changed. For a technical check, inspect the live page’s comments: fallback changes to dynamic after a successful replacement. FastPixel adds these labels; do not add them yourself. The saved page source still shows the cached fallback.

If it does not refresh, check the marker rules and ask your administrator to check compatibility and browser console errors.