<?xml version="1.0" encoding="UTF-8"?>

<sample>

  <name>xchart</name>
  <title>XChart Sample</title>
  <description>Shows how third-party charting APIs could be used for rendering charts as images.</description>

  <mainFeature ref="xchart"/>
  
  <!-- xchart -->
  
  <feature name="xchart" title="Rendering Images Using Third Party APIs (XChart Library)">
    <description>
How to render images using the <a href="http://knowm.org/open-source/xchart">XChart</a> library.
    </description>
    <since>6.4.3</since>
    <documentedBy>
      <author>
    	<name>Sanda Zaharia</name>
    	<email>shertage@users.sourceforge.net</email>
      </author>
    </documentedBy>
  	<otherSample ref="scriptlets"/>
  	<otherSample ref="jfreechart"/>
    <content>
<subtitle name="overview">The XChart Sample</subtitle>
<br/>
<br/>
This sample illustrates an interesting example of report scriptlets working in collaboration with third-party APIs, in order to output 
a chart image generated with the XChart library.
<br/>
First let's see the <code>XChartReport.jrxml</code> template in the <code>samples/xcharts/reports</code> directory. It provides a 
<code>scriptletClass="XChartScriptlet"</code> attribute, and a parametrized image element:
<pre><![CDATA[
<image scaleImage="Clip" hAlign="Center">
  <reportElement x="0" y="70" width="400" height="400"/>
  <graphicElement/>
  <imageExpression class="java.awt.Image"><![CDATA[$V{ChartImage}]] ></imageExpression>
</image>]]></pre>
The <code>java.awt.Image</code> object is stored in the <code>ChartImage</code> report variable:
<pre><![CDATA[
<variable name="ChartImage" class="java.awt.Image" calculation="System"/>]]></pre>
To see how the <code>ChartImage</code> variable was "calculated", let's dig a little into the <code>XChartScriptlet.java</code> file in the 
<code>src</code> directory:
<pre><![CDATA[
public void afterReportInit() throws JRScriptletException 
{
  try 
  {
    XYChart xyChart = new XYChartBuilder()
                          .width(400)
                          .height(400)
                          .title("Fruits Order")
                          .xAxisTitle("Day of Week")
                          .yAxisTitle("Quantity (t)")
                          .build();

    xyChart.addSeries("Apples", new double[] { 1, 3, 5}, new double[] { 4, 10, 7});
    xyChart.addSeries("Bananas", new double[] { 1, 2, 3, 4, 5}, new double[] { 6, 8, 4, 4, 6});
    xyChart.addSeries("Cherries", new double[] { 1, 3, 4, 5}, new double[] { 2, 6, 1, 9});
    XYStyler styler = xyChart.getStyler();
    styler.setLegendPosition(Styler.LegendPosition.InsideNW);
    styler.setAxisTitlesVisible(true);
    styler.setDefaultSeriesRenderStyle(XYSeries.XYSeriesRenderStyle.Area);

    BufferedImage bufferedImage = BitmapEncoder.getBufferedImage(xyChart);
    super.setVariableValue("ChartImage", bufferedImage);
  }
  catch(Exception e) 
  {
    throw new JRScriptletException(e);
  }
}]]></pre>
Here an area chart is created after the report initialization, using APIs in the XChart library. The chart is rendered as <code>java.awt.Image</code> and 
stored in the <code>ChartImage</code> variable. From now on, the chart image is ready to be used by the report filler when needed. 
<br/>
And that's all the story here. With only a report scriptlet and a third-party library, one could embed interesting, complex, spectacular objects in a given report.
<br/>
<br/>
<b>Running the Sample</b>
<br/>
<br/>
Running the sample requires the <a href="http://ant.apache.org/">Apache Ant</a> library. Make sure that <code>ant</code> is already installed on your system (version 1.5 or later).
<br/>
In a command prompt/terminal window set the current folder to <code>demo/samples/xcharts</code> within the JasperReports source project and run the <code>&gt; ant test view</code> command.
<br/>
It will generate all supported document types containing the sample report in the <code>demo/samples/xcharts/build/reports</code> directory. 
<br/>
Then the report will open in the JasperReports internal viewer.
    </content>
  </feature>

</sample>
