Frequently Asked Questions

Straight answers to the questions we hear most about TableCrafter v3.5.6 — what data sources work, how caching and refresh behave, where the real limits are, and how export, styling, and licensing fit together.

Data sources & setup

What data sources can TableCrafter read?

The single source attribute on the [tablecrafter] shortcode accepts three kinds of public URLs, and the plugin auto-detects which one you gave it:

• JSON APIs / endpoints — any URL that returns a JSON array (or an array nested under a key you point to with root).
• Google Sheets — a sheet shared as "Anyone with the link." TableCrafter recognizes any docs.google.com/spreadsheets/d/<id> URL and pulls the rows via Google's gviz endpoint.
• CSV files — any URL ending in .csv (including files you upload through the admin builder). CSV is parsed into rows server-side.

A minimal table is just a source:

[tablecrafter source="https://api.example.com/products.json"]

My JSON is nested. How do I point at the right array?

Use root with a dot path to the array you want to render. If your API returns {"items": {"list": [ ... ]}}:

[tablecrafter source="https://api.example.com/feed.json" root="items.list"]

Do I have to use shortcodes?

No. The same engine ships three ways to embed a table, all backed by the identical attributes:

Does TableCrafter store my data in the WordPress database?

No. TableCrafter is a viewer, not a store. It fetches data from your source on demand and keeps only a short-lived cached copy as a WordPress transient. Your wp_posts and wp_postmeta tables stay clean — nothing is imported or duplicated into them.

Caching, refresh & performance

How does caching work, and how fresh is the data?

TableCrafter uses a Stale-While-Revalidate (SWR) strategy. The rendered HTML and parsed data are stored in a transient for one hour. Visitors are served the cached copy instantly; once a cached entry is older than 5 minutes, the next page view schedules an invisible background refresh (via the tc_refresh_single_source WP-Cron event) so the cache is rebuilt without anyone waiting on your upstream API.

Can I make a table update live on its own?

Yes — that is separate from background caching. Enable client-side polling with auto_refresh and set the interval in milliseconds:

[tablecrafter source="https://api.example.com/live.json" auto_refresh="true" refresh_interval="30000" refresh_countdown="true"]

The default interval is 300000 (5 minutes). Companion attributes refresh_indicator, refresh_countdown, and refresh_last_updated control the on-screen refresh UI.

How do I clear or pre-warm the cache?

TableCrafter registers a WP-CLI command:

# Remove all cached TableCrafter transients
wp tablecrafter clear-cache

# Re-fetch and rebuild the cache for every tracked source
wp tablecrafter warm-cache

How big a dataset can it handle?

There is no hard row cap in the shortcode, but practical limits come from where the work happens:

For large feeds, trim what you load with include (whitelist columns) and paginate:

[tablecrafter source="https://api.example.com/big.json" include="name,price,symbol" per_page="25" search="true"]

Security & access

Is the server-side proxy safe to expose?

Yes. When you point at a remote URL, your server fetches it (which also sidesteps browser CORS errors), and that proxy is guarded several ways:

• SSRF protection — requests to localhost, 127.0.0.1, [::1], and private/reserved IP ranges are blocked, so the proxy cannot be used to probe your internal network.
• Rate limiting — capped at 30 proxy requests per 60-second window per client.
• SSL verification — enabled on all outbound requests to prevent man-in-the-middle tampering.
• Capability checks — admin actions (saving tokens, exporting, configuring) require the manage_options capability and a valid nonce.

Can I connect to a private / authenticated API?

The free version targets public sources or key-in-URL APIs (where the API key is part of the query string). For services that need header-based auth, OAuth, or token storage, the plugin can encrypt and store a token securely (used for the Airtable integration), but full OAuth/header auth is outside the free scope — see the Pro options below or contact us for a custom build.

Export

What export formats are supported, and are they real files?

Enable export with export="true". Three formats are produced by the canonical export handler (includes/class-tc-export-handler.php):

[tablecrafter source="https://api.example.com/orders.json" export="true" search="true"]

Files are generated server-side into a protected uploads subfolder (tablecrafter-exports/, locked down with an .htaccess deny rule), served through nonce-protected download URLs, and cleaned up automatically. Developers can adjust export templates via the tc_export_templates filter.

Styling & customization

How do I restyle the tables to match my theme?

TableCrafter renders standard HTML tables (and card layouts on mobile) with predictable, prefixed class names you can target from your theme's CSS:

High-contrast and focus states are driven by CSS variables such as --tc-border-color, --tc-text-color, --tc-bg-color, and --tc-focus-color, which you can override in your own stylesheet.

Are there JavaScript hooks for custom behavior?

Yes. The front-end script dispatches namespaced CustomEvents on the table container that you can listen for — for example reacting when a user taps a mobile card:

document.querySelector('.tablecrafter-container')
  .addEventListener('tablecrafter:cardTap', function (e) {
    console.log(e.detail); // row data + index
  });

Other dispatched events include tablecrafter:cardView and tablecrafter:cardEdit. For debugging, set window.TABLECRAFTER_DEBUG = true before the script runs to surface verbose logging.

Requirements, licensing & support

What are the requirements?

• WordPress: 5.0+ for the Gutenberg block; the shortcode works back to WordPress 3.0. Tested up to WordPress 7.0.
• PHP: 8.0 or newer (PHP 7 support was dropped in 3.5.2).
• Elementor: optional — the widget loads only when Elementor is present, so sites without it are unaffected.

How is it licensed, and what's the paid upgrade?

TableCrafter is free and licensed under GPLv2 or later. For teams that need editable, permissioned data, there's a separate premium product, Advanced Data Tables for Gravity Forms (formerly Gravity Tables), which adds frontend editing, role-based permissions, bulk actions, advanced filtering, conditional formatting, and Excel/CSV/PDF Pro export. Custom feature work and integrations are available for a fee — contact info@fahdmurtaza.com.

Next, see data-sources.html to dig into source-specific setup, and shortcode-reference.html for the full attribute list.