Server-Side Rendering
- Overview
- Environment
- Path
- Parameters
- Command Line Mode
- Web Server Mode
- Social Networks Sharing
- Requests
- Config File Format
- Contribution
Overview
Server-side rendering is a tool that is very helpful in many cases: when you have an automated email system, and you need to include charts in letters; when you need charts in reports that are generated on servers; when you need to show charts on a Smart TV with a stripped version of a browser; and so on. In such cases, we suggest that you use AnyChart Export Server.
AnyChart Export Server is also used to provide chart export to PNG, JPG, PDF, SVG, CSV, Excel, JSON, and XML.
Environment
AnyChart Export Server uses PhantomJS, which emulates a browser on the server (WebKit), runs our charts in it, gets SVG, and converts it into *.PNG, *.JPG, or *.PDF files. If you need to take a screenshot of a page on the Internet or in a local HTML file, you can just use Chrome or Firefox in the headless mode without the AnyChart Export Server. Export to Excel uses Apache POI. Exporting to CSV, JSON, and XML does not require PhantomJS: the server acts only as an intermediary allowing the file to be saved using a browser.
AnyChart Export Server is a Java application (JAR file) that runs using Java, so it works on Windows, Linux, MacOS, or any other OS where Java is available.
To run the AnyChart Export Server, do the following:
- Download PhantomJS from the PhantomJS official site and make sure PhantomJS binary is in the PATH.
- Install Firefox browser (version 56.0 and above) and install
geckodriver:brew install geckodriverfor Mac users- or download it from the geckodriver official site and add it to the PATH.
- Alternatively, install Chrome or Chromium browser (version 60.0 and above) and install
chromedriver:brew install chromedriverfor Mac users- or download it from the chromedriver official site and add it to the PATH.
- Install Java: version above 6, 7, 8 - https://java.com/en/download/).
- Download AnyChart Export Server binary file.
Path
PhantomJS
AnyChart Export Server needs PhantomJS. If its location is different from the default one, or you are installing Export Server on Windows, check the location where Phantom JS is installed and set the right path for the server:
java -Dphantomjs.binary.path=PATH_TO_YOUR_PHANTOMJS -jar
Export Server
If you have installed your own server and want AnyChart charts to use it for exports, use the anychart.exports.server() method in you JavaScript code and set the address of your server as a parameter:
anychart.exports.server("http://localhost:2000");
Parameters
The following arguments work both in Web Server Mode, and Command Line Mode:
| Name | Options | Description |
|---|---|---|
| –config PATH -C | Path to config | |
| –engine BROWSER -e | phantom, chrome or firefox | Headless browser |
| –help -h | Print help | |
| –version -v | Print version, can be used without action |
Command Line Mode
If you want to use AnyChart Export Server in Command Line mode, you should set cmd (Command Line) as the first parameter. Then define the path to the chart or insert the chart code as a string and set the parameters of the image: dimensions, quality, extension, and so on (see the list below).
A sample command line:
java -jar anychart-export.jar cmd --script "var chart = anychart.line([1,2,5]); chart.container('container'); chart.draw();" --output-path YOUR_OUT_PATH
The full list of the parameters available:
| Name | Options | Description |
|---|---|---|
| –script -s | The chart code | |
| –input-file -i | Set the path to the file with the chart code (script) | |
| –svg SVG | SVG string to Execute | |
| –svg-file SVG_FILE | SVG file to Execute | |
| –html-file HTML_FILE | The HTML page file to Execute (consider using just Chrome or Firefox binary in the headless mode instead) | |
| –output-file -o | The name for the output file (e.g.: "Chart1" or "Chart0.png") | |
| –output-path -p | Set the path for the folder where the chart will be saved | |
| –type -t | svg, png, jpg, pdf, csv, xlsx, xml, json | The file type |
| –container-id -c | The id for the container which will be generated in PhantomJS for the chart | |
| –container-width -W | The container width. The image quality will be better if the container is larger than the image. | |
| –container-height -L | The container height. The image quality will be better if the container is larger than the image. | |
| Export Images Parameters | ||
| –image-width -w | The image width. Doesn't work for *.pdf. Ignored when container-width is also set up - container-width will be used instead. | |
| –image-height -l | The image height. Doesn't work for *.pdf. Ignored when container-height is also set up - container-height will be used instead. | |
| –force-transparent-white -f | Make the chart background white if it is originally transparent | |
| –jpg-quality -q | from 0 to 1 | The image quality |
| Export PDF Parameters | ||
| –pdf-size -S | Define the *.pdf document paper size | |
| –pdf-x -x | The X-coordinate of the chart in the *.pdf document (in pixels) | |
| –pdf-y -y | The Y-coordinate of the chart in the *.pdf document (in pixels) | |
| –pdf-width -X | The *.pdf document height (in pixels) | |
| –pdf-height -Y | The *.pdf document height (in pixels) | |
| –pdf-landscape -O | Portrait or Landscape | The *.pdf document layout |
Web Server Mode
AnyChart Export Server is also used when you use AnyChart Export methods, and by default, AnyChart uses the server hosted at https://www.anychart.com/. Although we do our best to keep AnyChart site up and running 24x7x365, we do not guarantee the availability of the export server.
If you want to have full control over the ability of the component to export images or do not want to use AnyChart Server due to security or accessibility concerns, just run Export Server in Web Server mode on the server you control and trust.
To run Export Server in Web Server mode, set server as the first parameter. The host and port parameters are optional. In this mode, a usual HTTP web server is run. It receives POST requests and sends the result as a base64 line or as a Byte Array with the "File Transfer" header.
When you stop the server, you must stop the PhantomJS process too.
A sample of server running:
java -jar anychart-export.jar server
A sample of a command in the console:
curl -X POST -H "Accept: application/json" --data "responseType=base64&dataType=script&data=var chart = anychart.line([1,2,5]); chart.container('container'); chart.draw();" localhost:2000/png
The full list of the server parameters:
| Name | Options | Description |
|---|---|---|
| –host -H | The host where the server will be run | |
| –port -P | The port where the server will be run | |
| –log FILE -F | The file for server logging | |
| –allow-scripts-executing | y (yes), n (no) | A boolean parameter. Allows executing violent scripts in phantom js. If set to Y (e.g., as we do with https://export.anychart.com/), it might affect the security, so there is a flag, which is N by default. |
| Save images or *.pdf files to a folder | ||
| –saving-folder PATH -z | The path to save images or *.pdf files | |
| –saving-url-prefix PREFIX -Z | Return the URL prefix upon request | |
| Sharing | ||
| –sharing-port PORT | Share mysql database port | |
| –sharing-db NAME | Share mysql database name | |
| –sharing-user USER | Share mysql database user | |
| –sharing-password PASSWORD | Share mysql database password | |
| –twitter-key KEY | Twitter application key | |
| –twitter-secret SECRET | Twitter application secret | |
| –twitter-callback | Twitter application callback URL | |
Social Networks Sharing
AnyChart Export Server provides an ability to share chart images in social networks, such as Facebook, LinkedIn, Pinterest and Twitter.
When you use the export server on your own server and want sharing to work properly, you should set up –saving-folder and –saving-prefix. The first parameter is the path to the folder where images will be stored. The second parameter is the URL prefix which will be concatenated with the shared image name and returned to the user. You should provide the access to the shared image through that URL by setting up Nginx, for example.
Facebook, LinkedIn, Pinterest
Sharing on Facebook, LinkedIn, and Pinterest is implemented with the help of the commands for saving images. These social networks get the prepared picture via the link and just allow users to post it on the page.
Sharing images on Twitter is implemented with the AnyChart Twitter app. It requires MySQL database to be set up and uses three types of requests.
/sharing/twitter First of all, the user sends a request to /sharing/twitter that contains SVG or a script generating the image and posting in on the page. The request should contain the same parameters as a request to /png URL does. There are two options here: the user is authorized in the AnyChart Twitter application or not.
If the user is not authorized, the Twitter Authorization dialog is displayed. The user should confirm that he or she gives the app the rights to post the image. After that, the user will be redirected to the /sharing/twitter_oauth callback.
/sharing/twitter_oauth This request accepts the oauth_token and oauth_verifier parameters. Read more: OAuth (Wikipedia).
In the handler of /sharing/twitter_oauth request, the export server gets such params as oauth_token, oauth_token_secret, user_id, screen_name, image_url (user picture), and user_name and saves them to the MySQL database. After that, the posting images dialog window will be displayed.
If the user is already authorized in the app, the posting dialog will be displayed immediately. When the user confirms to post the image and clicks the TWEET button, there will be a request to /sharing/twitter_confirm.
/sharing/twitter_confirm This request should contain only Twitter message parameter - a string of no more than 140 characters. In the handler of /sharing/twitter_confirm request, the export server uploads the shared image with Twitter API and posts a new tweet with that image.
Note: the /sharing/twitter_oauth and /sharing/twitter_confirm requests are used inside Export Server, which means you do not need to send anything by yourself there.
If you want Twitter sharing to work through your server, you should:
- Create your own Twitter App and provide
twitter_key,twitter_secretandtwitter_callback(last path of which is always/sharing/twitter_oauth) to the Export Server - Setup a MySQL database for Twitter sharing using SQL scheme
- Setup a Twitter sharing URL separately when setting the
anychart.export.server()URL:
For more details check out AnyChart Exports API.anychart.exports.twitter( "http://your.export.server.url/sharing/twitter", "1000", "500" );
Requests
AnyChart Export Server supports the following requests:
| URL | Type | Description |
|---|---|---|
| /status | GET or POST | Server status |
| /png | POST | Export to PNG |
| /jpg | POST | Export to JPG |
| /svg | POST | Export to SVG |
| POST | Export to PDF | |
| /xml | POST | Export to XML |
| /json | POST | Export to JSON |
| /csv | POST | Export to CSV |
| /xlsx | POST | Export to XLSX |
| /sharing/twitter | POST | Twitter Sharing request |
| /sharing/twitter_oauth | GET | Twitter Sharing OAuth callback |
| /sharing/twitter_confirm | POST | Twitter Sharing posting confirmation |
Typical Export and Twitter Sharing request contains the params listed below:
| Parameter | Type | Default | Description |
|---|---|---|---|
| data | required | - | The script or SVG that will be transformed into a picture |
| data-type | required | - | A field that contains the information about the data. It might be "script" or "svg". |
| response-type | required | - | A field that tells how to export the result (as a file or as base64). |
| file-name | optional | anychart | The file name |
| save | optional | - | Return the URL of the saved image |
| container-id | optional | container | div container id |
| container-width | optional | 100% | div container width |
| container-height | optional | 100% | div container height |
| width | optional | 1024 | The image width |
| height | optional | 800 | The image height |
| quality | optional | 1 | The quality of the picture |
| force-transparent-white | optional | false | Make the background white or leave it transparent |
| pdf-size | optional | - | The sheet size of the *.pdf document |
| pdf-x | optional | 0 | The X-coordinate of the chart in the *.pdf document |
| pdf-y | optional | 0 | The X-coordinate of the chart in the *.pdf document |
| pdf-width | optional | 595 | The width of *.pdf |
| pdf-height | optional | 842 | The height of *.pdf |
| landscape | optional | false | The document orientation |
Config File Format
AnyChart Export Server provides an ability to pass all parameters within a config file using TOML format:
# can be "server" or "cmd"
mode = "server"
engine = "firefox"
[server]
port = 80
host = "0.0.0.0"
allow-scripts-executing = false
log = "/path/to/log/file"
[server.images]
# folder to save images
folder = "/export-server/shared"
# prefix which will be returned when saving image
prefix = "http://static.example.com/shared/"
[server.sharing]
# MySQL settings
port = 3306
db = "shared_db"
user = "export_server_user"
password = "export_server_password"
[server.sharing.twitter]
# settings from twitter app settings for sharing in Twitter
key = "key"
secret = "secret"
callback = "http://example.com/sharing/twitter_oauth"
[cmd]
# here you can pass cmd options for mode = "cmd"
script = "var chart = anychart.line([1,2,5]); chart.container('container'); chart.draw();"
output-file = "anychart"
output-path = ""
container-width = "1024px"
container-height = "800px"
container-id = "container"
input-file = "file.name"
type = "png"
image-width = 1024
image-height = 800
force-transparent-white = false
pdf-size = "a4"
pdf-x = 0
pdf-y = 0
pdf-width = 500
pdf-height = 500
jpg-quality = 1
You can pass a config file witn -C option, e.g.:
java -jar export-server.jar -C settings.toml
It should be noted here that if the same parameters are set both in the config file and in the command line, the former will be ignored because the command line has a higher priority.
Contribution
If you have any suggestions or ideas about Export Server work and improvements, welcome to AnyChart Export Server repository on GitHub.