Skip to content
ASTra

Charts and tables

Insert a native Word chart at a size you choose, change its data, series and type without losing the formatting the file already has, restyle it, and set the width and row heights of a table. Every example is a list of operations: save it as ops.json and run it with batch, or pass it as operations to execute_batch. These features arrived in version 0.5.3.

Insert a chart with a size and a description

widthIn and heightIn set the size in inches; widthEmu and heightEmu set it in EMU. Give one unit for each dimension, not both. A new two-dimensional chart is 6 by 2.6 inches, the allowed range is 0.1 to 22 inches, and a chart wider than the usable page width is inserted with a layoutWarning. altText is the description a screen reader reads.

json
[
  { "action": "chart", "operation": "insert", "anchor": "end", "id": "rev", "chartType": "column", "title": "Revenue",
    "categories": ["Q1", "Q2", "Q3"],
    "series": [{ "name": "North", "values": [4, 5, 7] }, { "name": "South", "values": [3, 4, 4] }],
    "widthIn": 6, "heightIn": 3, "altText": "Revenue by quarter, North and South" }
]

The style guide can set the defaults for every chart: a ## Charts section with Width, Height, 3D Width, 3D Height, Gridline Color, Font Family, Font Size and Title Size. A value in the operation beats the guide, and the guide beats the built-in default.

Change a chart in place

On chart update, a series list with more entries than the chart has adds series, removeSeries takes names or numbers and removes them, and a change among column, bar, stacked and percent types keeps the chart part and its formatting.

json
[
  { "action": "chart", "operation": "update", "target": "<chartNodeId>",
    "series": [{ "name": "North", "values": [4, 5, 7] }, { "name": "South", "values": [3, 4, 4] }, { "name": "East", "values": [2, 3, 5] }] },
  { "action": "chart", "operation": "update", "target": "<chartNodeId>", "removeSeries": ["South"] },
  { "action": "chart", "operation": "update", "target": "<chartNodeId>", "chartType": "bar" }
]

A chart node ID lasts for one session; read it again with inspect after you reopen the file. In a file written by Word, the chart part must be named word/charts/chart<number>.xml to be edited; the update says so when it is not.

What needs allowRebuild

Anything else that changes the structure of the chart (a different family such as column to pie, scatter, a combination chart, two-dimensional to three-dimensional) means writing the chart part again. ASTra does not do that silently. The call is refused before anything is written, and the refusal names what would be lost, for example a colour or a line width. Pass allowRebuild: true to accept it; the result then lists what the rebuild dropped under chartUpdates (formattingNotKept, styleNotApplied, updateMode).

json
[{ "action": "chart", "operation": "update", "target": "<chartNodeId>", "chartType": "pie", "allowRebuild": true }]

Chart data and the embedded workbook

  • A call that does not change data never touches the workbook stored inside the chart.
  • A call that changes data needs a workbook that ASTra can prove it wrote: rebuilt from the stored data, it must be the same part for part. Any other workbook is refused unless you pass allowRebuild: true.
  • A workbook that two charts share is refused or copied for the chart you update. A linked workbook is always refused.

Style a chart

The style key restyles an existing chart or sets the style on insert. The keys that came in 0.5.3:

titleFormatSize (sizePt), bold and color of the existing title. Needs at least one of them, and a title to format.
removeTitleUpdate only. Removes the title and shows no automatic one.
axis gridlineColorColour of the gridlines.
series[].points[]A colour for one point, counted from 1, in column, bar, pie, doughnut, line and scatter charts.
chartFontFont family and colour everywhere, and size everywhere except the title.
barsgapPercent and overlapPercent.
lineswidthPt, smooth and showMarkers.
chartArea, plotAreafillColor and borderColor.
axis labelSizePt, labelRotationDeg, showAxisLineAxis labels and the axis line.
json
[
  { "action": "chart", "operation": "update", "target": "<chartNodeId>",
    "style": { "titleFormat": { "sizePt": 14, "bold": true, "color": "1E293B" },
               "chartFont": { "family": "Calibri", "color": "334155" },
               "bars": { "gapPercent": 60, "overlapPercent": 0 },
               "plotArea": { "fillColor": "F8FAFC" } } }
]

Impossible values are refused at the call with a message that names the key. trendline.series is now trendline.seriesNumbers, counted from 1; the old key is refused.

Table width and row heights

setTableWidth takes one of widthIn, widthPercent (of the text width, or of the parent cell for a nested table) or widthTwips. columns: "scale" (the default) resizes the columns in proportion and rewrites every cell width; columns: "keep" changes only the table width. setRowHeights takes heightIn or heightTwips with a rule of atLeast or exact; auto removes the height.

json
[
  { "action": "table", "operation": "setTableWidth", "target": "<tableNodeId>", "widthPercent": 100, "columns": "scale" },
  { "action": "table", "operation": "setRowHeights", "target": "<tableNodeId>", "heightIn": 0.4, "rule": "atLeast" }
]

A floating table, a table whose cell spans do not add up, or a grid that cannot be trusted is refused and nothing is written. Percent widths use the real page: the paper size and the number of text columns of the section.

Known limits

  • Word and LibreOffice draw a few chart details differently, for example a smoothed line in a combination chart and the legend of a one-series chart with coloured points. The MCP specification lists them.
  • The charts, tables and layout of 0.5.3 are checked with the Open XML SDK, LibreOffice and by opening files in desktop Word. They are not part of the published benchmark.
  • A chart node ID lasts for one session.