Recipe: Live API Status Dashboard

Turn any JSON status endpoint into a self-updating WordPress dashboard. This recipe wires a single [tablecrafter] shortcode to TableCrafter's Smart Auto-Refresh engine so your table re-fetches on an interval, pauses politely while people read, and shows a live "updated X ago" indicator.

What you'll build

A status dashboard page showing the health of your services (component name, status, latency, last incident) that refreshes itself every 30 seconds without a page reload. The table preserves the visitor's current page, search, filters, and sort across each refresh, pauses while the tab is hidden or while someone is actively interacting, and exposes a small control bar to pause/resume or refresh on demand.

Everything here uses only real, shipped attributes from TableCrafter v3.5.6. No custom code is required, though we cover optional CSS theming at the end.

Prerequisites

• TableCrafter (wp-data-tables) v3.5.6 active on your site.
• A JSON endpoint that returns an array of rows (or an object containing one). Same-origin endpoints are fetched directly in the browser; cross-origin endpoints are routed through TableCrafter's server-side proxy automatically.
• A page or post where you can paste a shortcode (or a Gutenberg "TableCrafter Data Table" block / Elementor "TableCrafter Data Table" widget — all three render the same engine).

Step 1 — Inspect your API response shape

TableCrafter auto-discovers columns from the keys of the first row, so the shape of the response matters. The two common shapes:

A flat array — works with no extra attributes:

// GET https://status.example.com/api/components.json
[
  { "component": "API Gateway", "status": "operational", "latency_ms": 87 },
  { "component": "Database",    "status": "degraded",    "latency_ms": 412 }
]

A nested object — point at the array with the root attribute using dot notation:

// GET https://status.example.com/api/v1/summary.json
{
  "page": { "name": "Example Status" },
  "data": {
    "components": [
      { "component": "API Gateway", "status": "operational" }
    ]
  }
}
// reach the array with: root="data.components"

Step 2 — Add the dashboard shortcode

Create a new page (Pages → Add New), add a Shortcode block, and paste the example below. This is the core recipe — a 30-second live dashboard with a countdown timer:

[tablecrafter source="https://status.example.com/api/components.json"
  root="data.components"
  include="component,status,latency_ms,updated_at"
  search="true"
  filters="true"
  per_page="25"
  auto_refresh="true"
  refresh_interval="30000"
  refresh_countdown="true"
  refresh_last_updated="true"]

Publish, then view the page. On first load the server renders the table (Stale-While-Revalidate), then the frontend script hydrates it and starts the refresh loop. You should see a control bar reading "Auto-refresh active" with a live countdown and an "Updated just now" timestamp.

Step 3 — Curate the columns

Status APIs are often verbose. Trim the table to the columns that matter with include (a comma-separated allow-list) or exclude (a comma-separated hide-list). Column order follows the order of the keys discovered in the first row.

// Show only these four columns, in this priority
[tablecrafter source="..." include="component,status,latency_ms,updated_at"]

// Or keep everything except internal IDs
[tablecrafter source="..." exclude="internal_id,region_code"]

Add sort in column:direction format to land visitors on the most urgent rows first — for example sort="status:asc" or sort="latency_ms:desc".

Shortcode attribute reference

These are the attributes relevant to a live dashboard. Booleans accept true/false (also 1/yes).

How Smart Auto-Refresh behaves

Once auto_refresh="true", the TableCrafter instance starts a setInterval loop at your interval. Each tick calls performRefresh(), which:

1. Snapshots the visitor's current page, filters, search term, and sort.
2. Re-fetches the source (through the proxy for cross-origin URLs, with a 1-hour server transient cache on the proxy result).
3. Re-renders the table and restores that snapshot, so a refresh never yanks a reader back to page 1 or clears their filter.
4. Updates the "last updated" timestamp and resets the countdown.

Two "smart" guards keep it unobtrusive, both on by default:

• Pause on interaction: hovering, clicking, scrolling, moving the mouse, or typing inside the table pauses refreshing. It resumes automatically after 5 seconds of inactivity. This prevents the table re-rendering out from under someone mid-read.
• Pause on tab visibility: the loop pauses when the browser tab is hidden (via the visibilitychange event) and resumes when the tab is focused again — saving requests and battery.

If a refresh fails, the engine retries with exponential backoff (2s, 4s, 8s) up to 3 attempts. After the final failure it stops the loop to avoid hammering a down endpoint.

The control bar and its CSS hooks

When refresh_indicator is enabled, TableCrafter injects a control bar at the top of the container. These are the real class names you can target for theming:

The plugin injects baseline styles for these once, under a <style id="tc-refresh-styles"> tag. To restyle the bar (for example to match a dark dashboard), add your own CSS with higher specificity:

.tc-refresh-indicator {
  background: #0f172a;
  border-color: #1e293b;
  color: #e2e8f0;
}
.tc-refresh-indicator .tc-countdown { color: #38bdf8; }

Color-coding status values

TableCrafter renders cell values as text, so there is no built-in "status pill." The accurate way to color-code is plain CSS targeting the rendered cells. Because the table is re-rendered on every refresh, attribute-based selectors keep working after each update. A robust approach is to drive color from your data itself — return a CSS-friendly value and style by content using a small wrapper, or scope styles to the table cells:

/* Scope to your dashboard page/container, then style status text */
.tablecrafter-container td { font-variant-numeric: tabular-nums; }
/* Pair with a 'status' column whose values are operational/degraded/down */
.tablecrafter-container td:nth-child(2) { font-weight: 600; }

Tuning the refresh cadence

Manual control and instances

Each rendered table is a TableCrafter instance bound to its .tablecrafter-container. The visible ⏸️ and ↻ buttons map to toggleAutoRefresh() and refreshNow(). Visitors can pause a noisy dashboard themselves; the bar text and icon update to reflect the paused state. If you hide the bar with refresh_indicator="false", the loop still runs silently with the same smart pausing — useful for an unattended kiosk where you don't want controls on screen.

Troubleshooting

• Empty table. Your array is probably nested — set root to the dot path (the console logs a "Path segment not found" warning when the path is wrong).
• "Unable to load data." For cross-origin URLs, confirm the logged-in user can edit_posts (the proxy gate) and that the endpoint isn't a private/localhost address blocked by SSRF protection.
• Table never refreshes. Check that both auto_refresh="true" and a real source URL are present; inline-only data cannot poll.
• Refreshes feel slow on a remote API. That's the 1-hour proxy cache. Lower it or move the feed same-origin for literal-interval freshness.

Next, see data-sources.html to connect JSON, CSV, and Google Sheets sources (and configure nested root paths), and shortcode-reference.html for the full attribute list including export and pagination options.