JSON API - addChart

CONTENTS

LAYOUTS

TEMPLATES

FORMAT CONVERSION

DOCXPATH

DOCXUTILITIES

PDFUTILITIES

DOCXCUSTOMIZER

customizeWordContent

PERFORMANCE

addChart

PREMIUM

TRIAL / ADVANCED

Inserts a chart.

Note

You are reading the JSON API documentation. For the PHP API method please go to addChart.

This method allows the insertion of a chart into a Word document.

You may insert many different types of 2D and 3D charts:

2D:
- Bar (clustered, stacked and 100% stacked).
- Column (clustered, stacked and 100% stacked).
- Pie (simple, exploded, pie of pie and bar of pie).
- Doughnut.
- Line.
- Area.
- Surface.
- Radar.
- XY (scatter).
- Bubble.
3D:
- Bar: box (default), cylinder, cone, and pyramid (clustered, stacked and 100% stacked).
- Column: box (default), cylinder, cone, and pyramid (clustered, stacked and 100% stacked).
- Pie (simple and exploded).
- Surface.
- Line.
Extended charts (not supported by all DOCX readers):
- Box & whisker.
- Funnel.
- Histogram.
- Sunburst.
- Treemap.
- Waterfall.

This method also allows adding trendlines, grids, labels and many other chart features.

JSON data

{
    "data": {
        "legend": array,
        "data": array,
        "trendline": {
            "color": "string",
            "display_equation": boolean,
            "display_rSquared": boolean,
            "intercept": number,
            "line_style": "string",
            "type": "string",
            "type_order": number
        },
    },
    "type": "string",
    "title": "string",
    "border": number,
    "chartAlign": "string",
    "color": number,
    "excludeExternalData": boolean,
    "float": "string",
    "font": "string",
    "sizeX": number,
    "sizeY": number,
    "textWrap": number,
    "axPos": {
        "r": "string",
        "l": "string",
        "t": "string",
        "b": "string"
    },
    "formatCode": "string",
    "formatDataLabels": {
        "rotation": number,
        "position": "string"
    },
    "haxLabel": "string",
    "haxLabelDisplay": "string",
    "hgrid": number,
    "horizontalOffset": number,
    "majorUnit": number,
    "minorUnit": number,
    "orientation": array,
    "scalingMax": number,
    "scalingMin": number,
    "stylesTitle": {
        "bold": boolean,
        "color": "string",
        "font": "string",
        "fontSize": number,
        "italic": boolean,
        "layout": {
            "x": number,
            "y": number
        }
    },
    "vaxLabel": "string",
    "vaxLabelDisplay": "string",
    "verticalOffset": number,
    "vgrid": number,
    "legendOverlay": boolean,
    "legendPos": "string",
    "showCategory": boolean,
    "showLegendKey": boolean,
    "showPercent": boolean,
    "showSeries": boolean,
    "showTable": boolean,
    "showValue": boolean,
    "gapWidth": number,
    "groupBar": "string",
    "overlap": number,
    "tickLblPos": "string" | array,
    "explosion": number,
    "holeSize": number,
    "custSplit": array,
    "secondPieSize": number,
    "splitType": "string",
    "splitPos": number,
    "subtype": "string",
    "smooth": boolean | string,
    "symbol": "string",
    "symbolSize": number,
    "deleteAxisValues": boolean,
    "style": "string",
    "wireframe": boolean,
    "perspective": number,
    "rotX": number,
    "rotY": number,
    "chartAlign": "string",
    "color": "string",
    "legend": array,
    "legendPos": "string"
    "showLegend": boolean,
    "subtotals": array,
    "theme": {
        "chartArea": {
            "backgroundColor": "string"
        },
        "gridLines": {
            "capType": "string",
            "color": "string",
            "dashType": "string",
            "width": number
        },
        "horizontalAxis": {
            "textBold": boolean,
            "textDirection": "string",
            "textItalic": boolean,
            "textSize": number,
            "textUnderline": "string"
        },
        "legendArea": {
            "backgroundColor": "string",
            "textBold": boolean,
            "textItalic": boolean,
            "textSize": number,
            "textUnderline": "string"
        },
        "plotArea": {
            "backgroundColor": "string"
        },
        "serDataLabels": {
            "fontStyles": {
                "bold": boolean,
                "color": "string",
                "font": "string",
                "fontSize": number,
                "italic": boolean
            },
            "formatCode": "string",
            "position": "string",
            "showCategory": number,
            "showLegendKey": number,
            "showPercent": number,
            "showSeries": number,
            "showValue": number
        },
        "serMarkerOptions": {
            "borderColor": "string",
            "color": "string",
            "size": number,
            "symbol": "string"
        },
        "serRgbColors": array,
        "valueDataLabels": {
            "fontStyles": {
                "bold": boolean,
                "color": "string",
                "font": "string",
                "fontSize": number,
                "italic": boolean
            },
            "formatCode": "string",
            "position": "string",
            "showCategory": number,
            "showLegendKey": number,
            "showPercent": number,
            "showSeries": number,
            "showValue": number
        },
        "valueRgbColors": array,
        "verticalAxis": {
            "textBold": boolean,
            "textDirection": "string",
            "textItalic": boolean,
            "textSize": number,
            "textUnderline": "string"
        }
    }
}

Key	Description
data	This array should contain the legends and data and to be added to the chart.
type	The possible values are: areaChart area3DChart barChart bar3DChart bar3DChartCone bar3DChartCylinder bar3DChartPyramid boxWhiskerChart bubbleChart colChart col3DChart col3DChartCone col3DChartCylinder doughnutChart funnelChart histogramChart lineChart line3DChart ofPieChart (pie of pie and bar of pie charts) pieChart pie3DChart radarChart scatterChart sunburstChart surfaceChart treemapChart waterfallChart
title	The chart title.
border	Border width in points.
chartAlign	Chart alignment: left (default), right or center.
color	Word color scheme for charts: 1: greyscale. 2: default Word color scheme for charts. 3: blue scheme. For the remaining color schemes (up to 48) check the Word interface.
excludeExternalData	If true, don't embed the XLSX into the DOCX. Default as false.
float	Floating chart: left, right or center. It only applies if textWrap is not inline (default value).
font	The font to be used. Arial, Calibri...
sizeX	The chart width in centimeters (default value ~ 8.5 cm).
sizeY	The chart height in centimeters (default value ~ 6.0 cm).
textWrap	The way text shoud wrap the chart. Possible values are (check the Word interface for the graphical explanation of the different terms): 0 (inline) 1 (square) 2 (front) 3 (back) 4 (up and bottom)
trendline	Adds trendlines. Compatible with line, bar, col and area 2D charts. Possible keys and values are: "color" => HEX color. "display_equation" => display equation on chart. "display_rSquared" => display R-squared value on chart. "intercept" => set intercept. "line_style" => solid, dot, dash, lgDash, dashDot, lgDashDot, lgDashDotDot, sysDash, sysDot, sysDashDot, sysDashDotDot. "type" => exp, linear, log, poly, power, movingAvg. "type_order" => for poly and movingAvg types.

Chart display properties

Key	Description
axPos	Position of the axis (r, l, t, b). Each value of the array for each position (if a value is null avoids adding it).
formatCode	Number format.
formatDataLabels	Possible keys and values are: "rotation" "position" => center, insideEnd, insideBase, outsideEnd.
haxLabel	Label for the horizontal axis.
haxLabelDisplay	How to display the label of the horizontal axis. Possible values are: vertical, horizontal, rotated.
hgrid	Horizontal grid. Possible values are: 0 (no grid) 1 (only major grid lines - default) 2 (only minor grid lines) 3 (both major and minor grid lines)
horizontalOffset	Given in emus (1cm = 360000 emus).
majorUnit	Major unit value for bar, col, line, area, radar and scatter charts.
minorUnit	Minor unit value for bar, col, line, area, radar and scatter charts.
orientation	Orientation of the axis, from min to max (minMax) or max to min (maxMin). Each value of the array for each axis (if a value if null avoids adding it).
scalingMax	Scaling max value for bar, col, line, area, radar and scatter charts.
scalingMin	Scaling min value for bar, col, line, area, radar and scatter charts.
stylesTitle	Possible keys and values are: "bold" "color" => ffffff, ff0000... "font" => Arial, Times New Roman... "fontSize" => 1420, 2000... Size as drawing content (10 to 400000). 1420 as default "italic" "layout": "x" 0 < x < 1 "y" 0 < y < 1
vaxLabel	Label for the vertical axis.
vaxLabelDisplay	How to display the label of the vertical axis. Possible values are: vertical, horizontal, rotated.
verticalOffset	Given in emus (1cm = 360000 emus).
vgrid	Vertical grid. Possible values are: 0 (no grid) 1 (only major grid lines - default) 2 (only minor grid lines) 3 (both major and minor grid lines)

The available parameters to display legends and data include

Key	Description
legendOverlay	If true the legend may overlay the chart. This option may hinder the legibility of the data so it is only recommended if it is crucial to "save space".
legendPos	The possible values are: b (bottom) l (left) r (right) t (top) none
showCategory	If true shows the categories inside the chart.
showLegendKey	If true shows the legend values.
showPercent	If true shows the percentage values.
showSeries	If true shows the series values.
showTable	If true shows the chart data in an associated table.
showValue	If true shows the chart data values.

Further configuration options for specific chart types

Key	Description
Bar and column charts
gapWidth	Gap width.
groupBar	Different ways to group data. Possible values are: clustered, stacked, percentStacked and standard.
overlap	Overlap.
tickLblPos	Tick label position: nextTo, high, low, none. If string, uses default values. If array, sets a value for each position
Pie and doughnut charts
explosion	Distance among different sectors.
holeSize	Size of the inner hole (only doughnut charts).
ofPieCharts: pie of pie and bar of pie charts
custSplit	Custom split. Array (zero based) of values that goes in the second chart. For example: [3,4,7] will pick the fourth, fifth and eighth value.
gapWidth	Distance between the two charts.
secondPieSize	Percentage size of the auxiliary chart.
splitType	How to split the two charts. Possible values are: auto (default split type) cust (custom Split) percent (split by percentage) pos (split by position) val (split by value)
splitPos	Determines the threshold value to split the charts.
subtype	Defines if the auxiliary chart is a pie or bar chart. Possible values are pie or bar.
Line and scatter (XY) charts
smooth	If true it smooths the line. "0" forces disabling it
symbol	The possible symbol values are: Line charts: none, dot, plus, square, star, triangle, x, diamond, circle and dash. Scatter charts: dot and line.
symbolSize	The size of the symbol used.
Radar charts
deleteAxisValues	If true remove the axis values.
style	Defines the radar chart style. Possible values are: radar (lines without dots). marker (lines with dots). filled (filled enclosed area).
Surface charts
wireframe	If true the surface is shown as a wireframe.

Additional available options for 3D charts

Key	Description
perspective	Perspective angle. Angles beyond 25 degrees provoke a big distortion in the 3D chart representation.
rotX	Rotation angle with respect to the vertical axis. Standard values are between 10 and 20 degrees.
rotY	Rotation angle with respect to the horizontal axis. Standard values are between 10 and 20 degrees.

Extended charts supported options

Key	Description
chartAlign	Chart alignment: left (default), right or center.
color	colorful1 (default) colorful2 colorful3 colorful4 monochromatic1 monochromatic2 monochromatic3 monochromatic4 monochromatic5 monochromatic6 monochromatic7 monochromatic8 monochromatic9 monochromatic10 monochromatic11 monochromatic12 monochromatic13
legend	(data subarray) legends
legendPos	b (bottom) l (left) r (right) t (top) none
showLegend	If true shows the legend values.
sizeX	The chart width in centimeters (default value ~ 8.5 cm).
sizeY	The chart height in centimeters (default value ~ 6.0 cm).
style	style1 (default) style2 style3 style4 style5 style6 style7 style8 style9 style10
subtotals	(data subarray) subtotal indexes. Waterfall charts.
title	The chart title.

Theme options

Key	Description
chartArea	backgroundColor
gridLines	capType color dashType width
horizontalAxis	textBold textDirection: horizontal, rotate90, rotate270 textItalic textSize textUnderline (DrawingML values such as none, sng, dash)
legendArea	backgroundColor textBold textItalic textSize textUnderline
plotArea	backgroundColor
serDataLabels	fontStyles: bold color: ffffff, ff0000... font: Arial, Times New Roman... fontSize: size as drawing content (100 to 400000) (100 = 1pt). 1420 as default italic formatCode position (bottom, center, insideEnd, insideBase, left, outsideEnd, right, top). Each chart type supports specific positions. showCategory showLegendKey showPercent showSeries showValue
serMarkerOptions	borderColor: FF0000... color: FF0000... size: 1 to 73 symbol: none, dot, plus, square, star, triangle, x, diamond, circle, dash
serRgbColors	series colors
valueDataLabels	fontStyles: bold color: ffffff, ff0000... font: Arial, Times New Roman... fontSize: size as drawing content (100 to 400000) (100 = 1pt). 1420 as default italic position (bottom, center, insideEnd, insideBase, left, outsideEnd, right, top). Each chart type supports specific positions. showCategory showLegendKey showPercent showSeries showValue
valueRgbColors	values colors
verticalAxis	textBold textDirection (horizontal, rotate90, rotate270) textItalic textSize textUnderline (DrawingML values such as none, sng, dash)

Code samples

Example #1

{
    "actions": [
        {
            "action": "addText",
            "data": {
                "text": "We will now add a 3D pie chart to the Word document:"
            }
        },
        {
            "action": "addChart",
            "data": {
                "data": {
                    "data": [
                        {
                            "name": "data 1",
                            "values": [10]
                        },
                        {
                            "name": "data 2",
                            "values": [20]
                        },
                        {
                            "name": "data 3",
                            "values": [50]
                        },
                        {
                            "name": "data 4",
                            "values": [25]
                        }
                    ]
                },
                "type": "pie3DChart",
                "rotX": 20,
                "rotY": 20,
                "perspective": 30,
                "color": 2,
                "sizeX": 10,
                "sizeY": 5,
                "chartAlign": "center",
                "showPercent": true
            }
        },
        {
            "action": "addText",
            "data": {
                "text": "And now the same chart in 2D with a different color scheme and without the percentages:"
            }
        },
        {
            "action": "addChart",
            "data": {
                "data": {
                    "data": [
                        {
                            "name": "data 1",
                            "values": [10]
                        },
                        {
                            "name": "data 2",
                            "values": [20]
                        },
                        {
                            "name": "data 3",
                            "values": [50]
                        },
                        {
                            "name": "data 4",
                            "values": [25]
                        }
                    ]
                },
                "type": "pieChart",
                "color": 3,
                "sizeX": 10,
                "sizeY": 5,
                "chartAlign": "center"
            }
        }
    ]
}

Example #2

{
    "actions": [
        {
            "action": "addText",
            "data": {
                "text": "Chart with custom colors:"
            }
        },
        {
            "action": "addChart",
            "data": {
                "data": {
                    "legend": ["Series 1", "Series 2", "Series 3"],
                    "data": [
                        {
                            "name": "data 1",
                            "values": [10, 7, 5]
                        },
                        {
                            "name": "data 2",
                            "values": [20, 60, 3]
                        },
                        {
                            "name": "data 3",
                            "values": [50, 33, 7]
                        },
                        {
                            "name": "data 4",
                            "values": [25, 0, 14]
                        }
                    ]
                },
                "type": "colChart",
                "color": 3,
                "chartAlign": "center",
                "sizeX": 10,
                "sizeY": 10,
                "legendPos": "b",
                "legendOverlay": false,
                "border": 1,
                "hgrid": 3,
                "vgrid": 0,
                "groupBar": "stacked",
                "theme": {
                    "serRgbColors": [null, "FF00FF", "00FFFF"],
                    "valueRgbColors": [
                        ["FF0000"],
                        null,
                        [null, null, "00FF00"]
                    ]
                }
            }
        }
    ]
}

Release notes

phpdocx 18.0:
- new action.