Blocks and charts

Let an agent write posts and pages as native block-editor content, and draw charts from data instead of pasting images.

What it is and when to use it

CanAI pages are normally Twig. When you would rather open a page or post in the regular WordPress block editor, an agent can write it as blocks instead. The agent sends a structured list of blocks (headings, paragraphs, lists, images, columns, and so on) and CanAI hands it to WordPress core to turn into block markup. The result opens in the block editor without an "unexpected or invalid content" prompt.

Block types: paragraph, heading, list, quote, image, code, separator, embed, table, group, spacer, columns, buttons, cover, media_text, chart, and html. The html block is accepted only by write-page / create-page, and only when the user the write runs as has the unfiltered_html capability.

Twig page or blocks page?

Pick When
Twig The page needs loops, template context, t() translations or hand-tuned Tailwind markup
Blocks Editors want to maintain the body in Gutenberg, or it is mostly prose

A page is one or the other. Switching is deliberate and only available over MCP: the admin editor hands you a prompt for an agent instead of a toggle.

Charts

A chart is data, not a picture. The post stores labels and numbers; the browser draws them with Chart.js (bundled with the plugin, no CDN needed by default). The same data is also written out as a real table, so readers without JavaScript, reader mode, RSS and Markdown clients still get the numbers, and screen readers get a text alternative.

Kinds: bar, horizontal-bar, line, area, pie, doughnut, scatter, radar. Up to 8 series; pie and doughnut take exactly one.

Example: a chart in a post (MCP)

Add a block of type: "chart" to the blocks list of wpcanai/write-post or wpcanai/write-page:

{
  "type": "chart",
  "chart": "bar",
  "title": "Median response time",
  "labels": ["v1.0", "v1.1", "v1.2"],
  "datasets": [{ "label": "Median", "data": [420, 310, 190] }],
  "unit": "ms",
  "caption": "Lower is better.",
  "source": { "text": "Internal benchmark", "url": "https://example.com/bench" },
  "table": "collapsed"
}

Optional fields: stacked, y_min, y_max, height (160 to 800 pixels, default 320), className. table is collapsed (default, a closed "Show data" section), open, or hidden (visually hidden but still read by screen readers and Markdown clients). For scatter, each point is { "x": 1, "y": 2 } and labels is not used. Chart data is capped at 64 KB once serialised; aggregate or sample larger series.

Example: a chart in a Twig template

{{ wpcanai_chart({
  chart: 'line',
  title: 'Visitors per month',
  labels: ['Jan', 'Feb', 'Mar'],
  datasets: [{ label: 'Visitors', data: [1200, 1800, 2400] }],
  table: 'open'
}) }}

It takes the same keys as the block and reports problems as an HTML comment (<!-- CanAI wpcanai_chart(): ... -->) visible in view-source, so a bad chart never breaks the page.

Chart loading

Under Settings -> Libraries the Chart.js section has two options:

With no, a chart still prints its title, caption and data table, with a comment noting the loader is off.

To tweak a chart beyond what the block exposes (a second axis, line tension), listen for the wpcanai:chart:config browser event from your page JS and change event.detail.config. Keep listeners safe to run more than once: charts re-mount on dark-mode changes.

If something looks wrong

Symptom What it means
format_mismatch You wrote blocks onto a Twig page (or Twig onto a blocks page). Re-send with convert: true if you mean it
invalid_blocks / a chart error naming a field The block list failed validation; the message names the block position and the allowed values
truncation_blocked The new css is more than 70% smaller than a 1 KB+ existing value. Send confirm_truncate: true if intended
hash_mismatch You sent expected_hash for css and it changed since you read it. Re-read with wpcanai/read-meta
Chart shows a table but no drawing Chart.js loading is set to no, or JavaScript is blocked
Chart missing entirely The warnings array in the write result lists anything dropped or ignored; check it first

Related