Block Attributes Reference

The TableCrafter Gutenberg block tablecrafter/data-table exposes 14 saved attributes that control its data source, column visibility, search, filtering, export, pagination, and live auto-refresh behavior. This page documents every attribute as registered in register_block_type() and the editor's registerBlockType() call.

Overview

TableCrafter ships a single native block, registered as tablecrafter/data-table under the Widgets category. It is a dynamic block: the editor save function returns null, and all frontend markup is produced server-side by the PHP render_block_callback(), which forwards the attributes straight into the same engine that powers the [tablecrafter] shortcode. The block is registered on the WordPress init hook, so its attributes are available everywhere the editor and REST API run.

Insert the block from the editor inserter (search for "TableCrafter"), then configure every attribute visually through the sidebar (Inspector Controls). You do not edit attribute JSON by hand in normal use, but understanding the names is essential for theme integration, programmatic block insertion, and pattern building.

How attributes are stored and rendered

Attributes are persisted in the block's comment delimiter inside post content. On render, WordPress passes the attribute array to the PHP callback:

// register_block_type('tablecrafter/data-table', ...) render_callback
public function render_block_callback($attributes): string {
    if (empty($attributes['id'])) {
        $attributes['id'] = 'tc-block-' . uniqid();
    }
    return $this->render_table($attributes);
}

The callback injects every value into the front-end container as a data-* attribute (for example source becomes data-source, per_page becomes data-per-page, auto_refresh becomes data-auto-refresh). The bundled JavaScript reads those attributes to build the interactive table.

Core attributes

These attributes define what data is loaded and which columns appear.

Interactivity attributes

These toggles control the user-facing table controls. They are booleans in both the block registration and the editor; the PHP shortcode bridge also accepts the strings true, 1, and yes as truthy.

Auto-refresh attributes

Auto-refresh turns a static table into a live dashboard that re-fetches data on an interval. The four sub-options below only take effect when auto_refresh is enabled — the editor's "Auto-Refresh Settings" panel hides them until the master toggle is on.

Configuring attributes in the editor

Each attribute maps to a sidebar control under Settings → Block when the TableCrafter block is selected:

• Data Settings panel: Data Source URL (source), an "Upload CSV/JSON File" media button and a "Demo Data Sources" dropdown that both write to source, Data Root Path (root), Enable Search (search), Enable Column Filters (filters), Enable Export Tools (export), Rows Per Page (per_page), Include Columns (include), and Exclude Columns (exclude).
• Auto-Refresh Settings panel: Enable Auto-Refresh (auto_refresh), and — only once enabled — Refresh Interval (refresh_interval), Show Refresh Indicator (refresh_indicator), Show Countdown Timer (refresh_countdown), and Show Last Updated (refresh_last_updated).

The block renders a live, server-side preview inside the editor via wp-server-side-render, so changing a sidebar control re-renders the actual table rather than a placeholder.

Equivalent shortcode

Because the block and the [tablecrafter] shortcode share the same render engine, any block configuration can be expressed as a shortcode. A block with search, export, pagination, and auto-refresh enabled is equivalent to:

[tablecrafter
  source="https://example.com/api/employees.json"
  root="data.items"
  include="name,email,department,status"
  search="true"
  filters="true"
  export="true"
  per_page=25
  auto_refresh="true"
  refresh_interval=60000
  refresh_countdown="true"]

The matching block markup stored in post content looks like this:

<!-- wp:tablecrafter/data-table {
  "source":"https://example.com/api/employees.json",
  "root":"data.items",
  "include":"name,email,department,status",
  "search":true,"export":true,"per_page":25,
  "auto_refresh":true,"refresh_interval":60000,"refresh_countdown":true
} /-->

Notes and edge cases

• Empty source: with no source, the front end renders a friendly empty-source placeholder rather than an error.
• Boolean coercion: the block stores real booleans, but the shared render path also accepts the strings true, 1, and yes as true for shortcode parity.
• Auto-generated id: if id is blank, the block produces a unique tc-block-{uniqid} id at render time so multiple tables never collide on the page.
• No sort attribute: initial sort order (column:direction) is a shortcode-only attribute and is not part of the block's registered attributes.
• Demo sources: the editor's "Demo Data Sources" dropdown is populated from localized data and simply writes a sample URL into the standard source attribute — it is not a separate attribute.

Next steps

For the full attribute set including sort and string-based booleans, see shortcode-reference.html. To learn how nested JSON, CSV, and Google Sheets sources are parsed before rendering, continue to data-sources.html.