Command Line Rendering#

Node Export Server#

In addition to being able to run as a server, our node export server is a fully functional command line tool for creating chart images in PNG, JPEG, PDF or SVG, based on chart configurations or chart SVGs. Whether you want to generate charts in automated reports or emails, have consistent images between front and back end, or simply batch convert charts to images, the node export server is your tool.

Install with npm install highcharts-export-server -g or clone from https://github.com/highcharts/node-export-server

The tool has a simple command line syntax: highcharts-export-server <arguments>

Examples:

  • Convert a chart configuration to a PNG image: highcharts-export-server -infile chartConfig.json -outfile chart.png
  • Batch convert three charts into images: highcharts-export-server -batch "infile1.json=outfile1.png;infile2.json=outfile2.png;infile3.json=outfile3.png;"

See documentation on GitHub for more information

Deprecated Export Server#

Our older, legacy export server includes a PhantomJS script package, which makes it possible to run Highcharts on the server without a client internet browser involved. Note that there are no features in the legacy export server which are not included in the new node export server.

Typical use cases are:

  • you want to include your charts in emails or automated management reports
  • you want to have a consistency between graphs you present on your website and your backend produced reports

We're using PhantomJS for this, which emulates a browser environment (Webkit) on the server. PhantomJS comes with a JavaScript API and we used this for making a script for converting our graphs to another file format. In summary, it works like this; the script (highcharts-convert.js) starts a browser, opens a page with Highcharts loaded in it and produces a chart and saves it as an image, PDF or SVG.

Command line usage#

PhantomJS is started from the command line with our highcharts-convert.js script as first parameter. With the other command line parameters we pass over the Highcharts configuration, the name of the output file and parameters for the graphical layout. Example usage on the command line:

phantomjs highcharts-convert.js -infile options.js -outfile chart.png -scale 2.5 -width 300

Description of command line parameters:

-infile

The file to convert, the script has to find out if this is a javascript file with an options object or a svg file.  It checks if the input file begins with <svg, <?xml or <!doctype. If it does then it's a svg file, otherwise it's presumed to be an options file.

-outfile

The file to output. Must be a filename with the extension .jpg, .png .pdf or .svg.

-type

The type can be of jpg, png, pfd or svg. Ignored when -outfile is set. This parameter is useful when the script runs in servermode and outputs an image as a 64bit string. When not running in servermode the output file is stored in -tmpdir.

-scale

Set the zoomFactor of the page rendered by PhantomJs. For example, if the chart.width option in the chart configuration is set to 600 and the scale is set to 2, the output raster image will have a pixel width of 1200. So this is a convenient way of increasing the resolution without decreasing the font size and line widths in the chart. This is ignored if the -width parameter is set.

-width

Set the exact pixel width of the exported image or pdf. This overrides the -scale parameter.

-constr

The constructor name. Can be one of Chart or StockChart. This depends on whether you want to generate Highcharts Stock or basic Highcharts.

-callback

File containing a JavaScript callback. The callback is a function which will be called in the constructor of Highcharts to be executed on chart load. All code of the callback must be enclosed by a function. Example contents of the callback file: function(chart) { chart.renderer.arc(200, 150, 100, 50, -Math.PI, 0).attr({ fill : '#FCFFC5', stroke : 'black', 'stroke-width' : 1 }).add(); }

-resources

Stringified JSON which can contain three properties: js, css and files. Example:

{
"files": "highstock.js,highcharts-more.js,data.js,drilldown.js,funnel.js,heatmap.js,treemap.js,highcharts-3d.js,no-data-to-display.js,map.js,solid-gauge.js,broken-axis.js",
"css": "g.highcharts-series path {stroke-width:2;stroke: pink}",
"js": "document.body.style.webkitTransform = 'rotate(-10deg)';"
}
  • files: A comma separated string of filenames that need to be injected to the page for rendering a chart. Only files with the extensions .css and .js are injected, the rest is ignored.
  • css: Css inserted in the body of the page
  • js: Javascript inserted in the body of the page

-host

Specify the host for running the script as a lightweight HTTP server. The server responds to JSON objects sent to the server in a POST request.

-port

The port number PhantomJS is listening on for POST requests.

-tmpdir

Specify where the scipt stores temporary- or output files, when output isn't defined.

Start as a web server#

You can also let the script start a web server. By doing so, we don't have to start a PhantomJS process over and over again for every conversion job and this results in better performance. While running the script in web server mode, the result isn’t saved to a file, but returned as a base64 string, unless when you want to export to SVG or PDF.

This is how you start a web server in PhantomJS with the highcharts-convert.js script, change the host and port to your needs. However do not expose the PhantomJS web server to the outside world, it’s not intended as a general production server.

phantomjs highcharts-convert.js -host 127.0.0.1 -port 3003

Note that the web server listens only to POST requests. Use the same parameters as for command line usage, but wrap them in a JSON structure. See this example for the content of a POST request. Note that these parameters are defined: infile, callback and constr;

{"infile":"{xAxis: {categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']},series: [{data: [29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4]}]};","callback":"function(chart) {chart.renderer.arc(200, 150, 100, 50, -Math.PI, 0).attr({fill : '#FCFFC5',stroke : 'black','stroke-width' : 1}).add();}","constr":"Chart"}

This is how you can send a POST from the command line with curl (Mac & Linux):

curl -H "Content-Type: application/json" -X POST -d '{"infile":"{xAxis: {categories: [\"Jan\", \"Feb\", \"Mar\"]},series: [{data: [29.9, 71.5, 106.4]}]}"}' 127.0.0.1:3005

Example of sending the contents of a file:

curl http://127.0.0.1:3005 -H "Content-Type: application/json" -X POST --data-binary "@/Users/yourname/yourfolder/chart-config.json"

This is how you can send a POST from the command line with curl (Windows):

curl -H "Content-Type: application/json" -X POST -d "{\"infile\":\"{series:[{data:[29.9,71.5,106.4]}]}\"}" 127.0.0.1:3005
Setting it up#
  1. To download and install of PhantomJS, see https://phantomjs.org/download.html.
  2. Clone the highcharts-export-server repository from GitHub or download the zip file containing the repository and copy the phantomjs folder to your installation folder.
  3. In the copied phantomjs folder is a file named resources.json. This file specifies the Highcharts javascript files for creating the charts. Make sure the files can be looked up through the resources.json file. The files will be looked up relative to the working directory of PhantomJS, but you can also specify your own locations.
  4. If you experience issues with PDF export not matching the page size, try changing the dpiCorrection setting in the highcharts-convert.js script. The issue is likely related to this PhantomJS bug.
  5. You're good to go!