FusionCharts helps you make kick-ass dashboards that can be viewed on a PC, Mac, iPad, iPhone or a majority of mobile devices. To view these dashboards, you open your favorite browser, go to the URL of the dashboard either by typing in or clicking through, the browser loads the content and FusionCharts, and you finally get to see your interactive dashboards. It all works fine! But, what if your management asks you to deliver the dashboard through email at the end of each day, so that they do not have to remember to visit the dashboard?
What is FCImg?
The chart images generated by FCImg could be used in the following scenarios:
- When you need to email dashboards or reports containing FusionCharts
- When you need to build PDFs of reports or dashboards and embed FusionCharts
Setting up FCImg
To get FCImg for your server, choose the right variant from the list below:
- Windows (32 Bit & 64 Bit) [8.9 MB] [ZIP]
- Linux (32 Bit) [10 MB] [tar.gz]
- Linux (64 Bit) [10 MB] [tar.gz]
The system requirements to run FCImg are:
- Linux or Windows operating systems. Shared hosts are also supported. safe_mode should not be enabled. (Note that safe_mode is deprecated and disabling it is highly recommended. Most hosts disable safe_mode by default).
- PHP 5.2 or above.
After downloading the appropriate variant, extract the package to a path on your server that is accessible by your PHP Scripts. You will find that there is only one folder – fcimg. Inside this folder, you will find a /bin sub-folder, fcimg.php and template.txt. Next, you will need to set the right permission for the /bin folder contained within this folder. On Linux systems, the contents of /bin needs to be executable. If you downloaded and extract the files directly on the server, the file permissions are already set. However, if you transferred the files using FTP, then you need to set the permissions manually using this command from the directory where you extracted fcimg:
[cciel lang=”bash”]chmod +x fcimg/bin/*
Using FCImg is fairly simple. You include the fcimg.php file and invoke fusioncharts_to_image function with a bunch of parameters, as listed and explained below.
"/var/www/report.png", // Full path to output image, including name.
"Column3D.swf", // SWF Alias of chart. Note: SWF File is NOT required.
// It's just a pointer to which chart type to render.
$inputString, // The input XML data string for the chart
400, 500, // Height and width of the chart
array( // Additional options for conversion
'imageType' => 'jpg', // Setting image type as JPG
'quality' => 75 // Increase output quality
The fusioncharts_to_image method takes the following arguments, listed in order:
- outputFilePath: The full path to the output image. If this file already exists, it will be overwritten.
- swfName: The FusionCharts SWF filename which will be used to determine which type of chart to render.
- inputString: The Data String in XML or JSON format. Note that the converter will automatically determine whether the input is XML or JSON.
- height: The height of the chart in pixels.
- width: The width of the chart in pixels.
options: This is an array to configure optional parameters. This is treated as a key-value set.
- $options["imageType"]: Specifies the type of the image (png/jpg). Default: png.
- $options["quality"]: The Image quality (0-100). Note that a higher quality might take longer to render. Default: 70.
What happened behind the scenes?
When this script executed, the following actions happened behind the scenes:
- It created a virtual Webkit browser and opened the generated HTML file inside that browser.
- It waited 1500 milliseconds for the animations to complete.
- It captured the image on this virtual Webkit browser, converted that into image using wkhtmltoimage, and saved it at the path provided.
FCImg takes a couple of seconds to export a single chart on a basic server. This delay is intended because the default animations of FusionCharts take up to 1.5 seconds to complete on certain charts. The fusioncharts_to_image function is a blocking call. It means that the PHP script will not continue until the rendering process is complete (unlike event based callback systems). It is best to call this method in PHP scripts that run on the server directly and do not serve output to browsers e.g., in a script that generates emailed reports, or a script that is executed through a cron-job.
- Remove the contents of template.txt found in the fcimg directory
- Add all the code from jQuery charts jquery.min.js to template.txt
- Add all the code from FusionCharts.js to template.txt
- Add all the code from FusionCharts.HC.js to template.txt
- Add all the code from FusionCharts.HC.Charts.js to template.txt
Note that the order of files added is important.
Getting on with it
Do give FCImg a spin. It’s useful. It’s free. And if you encounter some painful situations, give a shout to the developer at firstname.lastname@example.org. It will help if you include details like the XML/JSON data.