Skip to main content

Block Visibility Timed Reveals

This integration lets Yoko Core coordinate timed Block Visibility content without depending on a fast external cron runner. It prepares future visibility changes ahead of time, annotates the rendered block with timing metadata, and uses a small frontend script to hide or reveal the block at the right moment.

It is designed for blocks that use Block Visibility's dateTime control, including schedule payloads that contain start, end, isSeasonal, timeOfDay, and dayOfWeek fields.

Overview​

Yoko Core adds three pieces to the Block Visibility flow:

  1. Server-side scheduling for cache refreshes before a visibility boundary changes.
  2. Render-time metadata so timed blocks can be shipped in cached HTML when they are close enough to a reveal.
  3. Client-side evaluation so the browser can hide or reveal a prerendered block without waiting for a hard refresh.

This is useful when the site uses page caching and you need a block to change state at a specific time rather than on the next uncached request.

How It Works​

When a post is saved, Yoko Core scans the parsed block tree and looks for blockVisibility settings containing dateTime schedules. For each enabled schedule boundary, it calculates the target time and stores a schedule map on the post.

If the site has Action Scheduler available, Yoko Core uses that backend. If not, it can fall back to native WP-Cron.

When a timed block is rendered, Yoko Core adds a payload to the block data and annotates the outer HTML element with data attributes such as:

  • data-yoko-bv
  • data-yoko-bv-windows
  • data-yoko-bv-transitions
  • data-yoko-bv-next-reveal
  • data-yoko-bv-next-hide

The frontend script reads those attributes and updates the block's visibility state when the scheduled time arrives.

Supported Block Visibility Shapes​

This integration is intentionally defensive because Block Visibility has changed its payload shape over time.

It supports:

  • modern blockVisibility.controlSets[*].controls.dateTime.schedules[*] payloads
  • older payloads that expose dateTime more directly
  • seasonal schedules with:
    • isSeasonal
    • timeOfDay
    • dayOfWeek

Only timed visibility data is converted into client-side timing metadata. If a control set also depends on unrelated runtime conditions such as cookies, query vars, roles, or metadata, Yoko Core keeps that block server-controlled so the browser does not accidentally reveal content that should stay hidden.

Frontend Behavior​

Timed blocks get prerendered into the page when the reveal is close enough to fall inside the configured prerender window. That lets the page cache include the future markup ahead of time.

On the client, the script:

  • reads the timing windows from the data attributes
  • hides blocks that should not yet be visible
  • reveals them at the scheduled time
  • rechecks on pageshow, visibilitychange, and a periodic timer so the state stays correct even if the tab was inactive

This makes the feature cache-friendly while still giving the visitor the right state on screen.

Filters​

yoko_block_visibility_client_prerender_seconds​

Controls how far ahead a hidden timed block should still be included in cached HTML so the frontend can reveal it later.

Default: HOUR_IN_SECONDS

Example:

add_filter(
	'yoko_block_visibility_client_prerender_seconds',
	function () {
		return 2 * HOUR_IN_SECONDS;
	}
);

yoko_block_visibility_client_horizon_seconds​

Controls how far ahead Yoko Core should look when building the client payload and transition windows.

Default: 7 * DAY_IN_SECONDS

yoko_block_visibility_scheduler_backend​

Overrides the scheduler backend used for timed refresh actions.

Allowed values:

  • auto
  • action-scheduler
  • wp-cron

Example:

add_filter(
	'yoko_block_visibility_scheduler_backend',
	function () {
		return 'wp-cron';
	}
);

Native WP-Cron​

The integration can be initialized with native cron forced on:

\YokoCo\Integrations\BlockVisibility::init( true );

Use that when you want to bypass Action Scheduler and rely on native WordPress scheduling instead. The default remains false, which keeps the normal auto-detection behavior in place.

Cache Refresh Lifecycle​

When a post is saved, Yoko Core:

  1. scans the block content for timed schedules
  2. stores a normalized schedule map for the post
  3. queues refresh actions for the upcoming boundary windows
  4. clears the queued actions when the post is deleted or changed to draft/private

That lifecycle keeps the scheduled queue aligned with the actual post state.

Compatibility Notes​

  • The integration is compatible with older and newer Block Visibility date/time payload shapes.
  • Timed blocks are only prerendered when their reveal is inside the configured prerender window.
  • If the current block depends on more than date/time visibility, it stays server-controlled.
  • The frontend script is added only when a block actually needs timed visibility metadata.

Example Payload​

Example Block Visibility schedule shape supported by the integration:

{
  "blockVisibility": {
    "controlSets": [
      {
        "id": 1,
        "enable": true,
        "controls": {
          "dateTime": {
            "schedules": [
              {
                "enable": true,
                "start": "2026-05-20T17:41:00",
                "end": "2026-05-21T19:00:00",
                "isSeasonal": true,
                "timeOfDay": {
                  "enable": true,
                  "intervals": [
                    {"start": "00:00:00", "end": "12:00:00"},
                    {"start": "13:00:00", "end": "15:00:00"}
                  ]
                },
                "dayOfWeek": {
                  "enable": true,
                  "days": ["Mon", "Wed"]
                }
              }
            ]
          }
        }
      }
    ]
  }
}

Practical Guidance​

Use this integration when you want a timed block to behave correctly on a cached page.

Use the prerender window filter to decide how aggressively Yoko Core should include future markup in the HTML output.

If you need a page to flip state as close to the exact timestamp as possible, native client-side timing is the part that actually updates the browser. The scheduler only ensures the HTML and cache are prepared in advance.