Charting API Change Proposal
From OpenLaszlo
API Specification
A change to the charting and graphing API that introduces an entirely new set of charting and graphing components that are significantly easy to use, faster, more versatile, and more expansible. It's a rewrite basically from the ground up.
You can view the documentation files for a detailed breakdown of the components proposed, along with a handful of live examples, at http://www.incessantscreaming.com/lzcharting/ though there are still a handful of bugs that have yet to be resolved, particularly with zooming, and the components have not yet been updated to work with OpenLaszlo 4.2 or greater.
Backwards compatibility will be retained by moving the existing charting and graphing components into a directory in the "components" directory called "deprecated".
Justification for API Change
With the current charting and graphing components we offer, the API is convoluted and confusing. In order to even get a chart to draw, one must define a separate file called a “chartstyle”, which is a gigantic labyrinthine .lzx file filled with every possible attribute that could possibly be defined on any given chart of any type. To make any changes at all to the appearance of a chart, one must search through a solid page and a half of definitions.
Instead, we should move all the definitions out of a separate file and onto the components themselves (as they currently are with our other components), providing default values and allowing the developer to customize appearance by changing the attributes on the chart components they wish to modify, instead of some other strange, confusing, all-encompassing “style” file. Thus, in order to draw a basic barchart with default appearance, one need only have the following:
<canvas width="600" height="500">
<dataset name="dset" request="true" src="resources/barchart_data_02.xml"/>
<barchart name="testchart" width="500" height="400" datapath="dset:/">
<chartdata>
<dataseries ydatapath="salesdata/fy2005/month/@amount"
datacolor="0xAABBDD" label="salesdata/fy2005/month/@amount"/>
<dataseries ydatapath="salesdata/fy2006/month/@amount"
label="salesdata/fy2006/month/@amount" datacolor="salesdata/fy2006/month/@color"/>
</chartdata>
</barchart>
</canvas>
And to fully customize the chart's visual appearance and behavior, one might have this:
<canvas width="600" height="500">
<dataset name="dset" request="true" src="barchart_data_02.xml"/>
<barchart name="testchart" width="500" height="400" datapath="dset:/"
hgridlines="#666666" hgridspacing="10" hgridwidth="2" minimum="-5" maximum="60"
vgridlines="#EE00EE" vgridspacing="7" vgridwidth="2" border="#550000"
vgridbands="#AAAAAA" vbopacity=".3" bgresource="pics/gable.jpg"
hgridbands="#EEEEEE" hbopacity=".5" plotheight="300" ploty="40"
plotwidth="350" plotx="100" htick="#005500" vtick="#FFEEDD" vticklabel="#221100"
belowzero="#CCBB88" hticklabel="#005500" bgcolor="#AF9B80" drawaxis="x"
belowzeroopacity=".5" drawzero="#880000" baselabels="#FFEEDD"
haxis="#FFEEDD" vaxis="#005500">
<text x="5" y="5" text="Gable Sales, FY 2005-2006" fgcolor="#FFEEDD"
fontsize="14" fontstyle="bold"/>
<text x="5" y="190" text="Quantity" fontstyle="bold" fgcolor="#FFEEDD"
onclick="parent.setAttribute('zoomable', !parent.zoomable);
parent.setAttribute('draggable', !parent.draggable);"/>
<text x="250" y="375" text="Month" fontstyle="bold" fgcolor="#FFEEDD"/>
<chartdata>
<dataseries animationinit="rain" ydatapath="salesdata/fy2005/month/@amount"
datacolor="salesdata/fy2005/month/@color" tooltip="true"
legenddatapath="salesdata/fy2005/@year"
label="salesdata/fy2005/month/@amount" labelcolor="#669988" labelborder="#44DD66"
labeltextcolor="#FFEEDD" baselabels="salesdata/fy2005/month/@month"/>
<dataseries ydatapath="salesdata/fy2006/month/@amount"
legenddatapath="salesdata/fy2006/@year"
label="salesdata/fy2006/month/@amount" datacolor="salesdata/fy2006/month/@color"
animationinit="rain"
labelcolor="#AA5577" labelborder="#DD3355" labelborderwidth="2"
baselabels="salesdata/fy2006/month/@month" labeltextcolor="#FFEEDD"/>
</chartdata>
<chartlegend ltitle="Fiscal Year" width="150" height="30"
x="${parent.plotx + parent.plotwidth - this.width}"
y="${parent.ploty - this.height}" hlcolor="#DDCCBB" textcolor="#FFEEDD"
titlecolor="#FFEEDD" resizetodata="wide" backcolor="#BFAC91" border="#550000"/>
</barchart>
</canvas>
Note that while there are a number of attributes defined here, this customizes nearly every visual attribute on the chart, from the background to the individual bars to the legend. This is a significant improvement from our current method using defaultchartstyle.lzx and chartstyle.lzx and whatever else needs to be defined.
Attributes can also be defined using data. In the example above this attribute is defined on one of the <dataseries/> objects:
datacolor="salesdata/fy2006/month/@color"
The corresponding data is:
<fy2006 year="2006"> <month month="Jan" amount="1" color="0xAA5577"/> <month month="Feb" amount="9" color="0xAA5577"/> <month month="Mar" amount="35" color="0xAA5577"/> <month month="Apr" amount="7" color="0xAA5577"/> <month month="May" amount="19" color="0xAA5577"/> <month month="Jun" amount="11" color="0xAA5577"/> <month month="Jul" amount="8" color="0xAA5577"/> <month month="Aug" amount="14" color="0xAA5577"/> <month month="Sep" amount="29" color="0xAA5577"/> <month month="Oct" amount="47" color="0xDD3355"/> <month month="Nov" amount="18" color="0xAA5577"/> <month month="Dec" amount="6" color="0xAA5577"/> </fy2006>
Thus, every bar would have the color ascribed it in the data. One could change any given value for “color” in the data and the corresponding bar on the chart would be that color. There are other attributes that share this behavior.
One can now also dynamically alter the orientation of the bars, from horizontal to vertical. This wasn't possible. Bars can also be animated – there is a base range of animations available that can easily be expanded, or customized by developers to fit their aesthetic needs.
Regarding piecharts, multiple pies can now be drawn, if desired, and clicking on individual pies will maximize/minimize them. See the following example, where four different pies are drawn using different values within the same set of data:
<canvas width="800" height="600">
<dataset name="dset" request="true" src="piechart_data_01.xml"/>
<piechart name="testchart" width="600" height="400" datapath="dset:/"
plotx="10" ploty="10" plotwidth="580" plotheight="380" bgcolor="#333345">
<chartdata>
<dataseries xdatapath="data/show/@hours" datacolor="data/show/@color"
explode="true" label="data/show/@title" piebgcolor="#BBBBCD"
legend="left" labelcolor="#000001" labelborder="#DDDDD9"
labeltextcolor="#EEEEE0" legendtitle="Hours" drawbg="#EEEEE0"
drawbgborder="#9999AB" legendbg="#9999AB" bgborderwidth="3"
legendhl="#DDDDEF"/>
<dataseries xdatapath="data/show/@viewers" datacolor="data/show/@color"
explode="true" label="data/show/@title" piebgcolor="#CDBBBB"
legend="right" labelcolor="#000001" labelborder="#DDDDD9"
labeltextcolor="#EEEEE0" legendtitle="Viewers" legendbg="#AB9999"
showlegendminimized="false" drawbg="#EEEEE0" drawbgborder="#AB9999"
legendhl="#EFDDDD"/>
<dataseries xdatapath="data/show/@dvd" datacolor="data/show/@color"
explode="true" label="data/show/@title" piebgcolor="#BBCDBB"
legend="bottom" labelcolor="#000001" labelborder="#DDDDD9"
labeltextcolor="#EEEEE0" showlegendminimized="false"
legendtitle="DVD" legendtitleposition="center" drawbg="#EEEEE0"
legendbg="#99AB99" legendhl="#DDEFDD"/>
<dataseries xdatapath="data/show/@cost" datacolor="data/show/@color"
explode="true" label="data/show/@title" piebgcolor="#CDBBCD"
labelcolor="#000001" labelborder="#DDDDD9" labeltextcolor="#EEEEE0"
legend="top" legendtitle="Cost" legendtitleposition="right"
legendhl="#EFDDEF" drawbg="#EEEEE0" drawbgborder="#AB99AB"
bgborderwidth="5" legendbg="#AB99AB"/>
</chartdata>
</piechart>
</canvas>
And the corresponding data:
<data> <show title="Mr. Show" hours="9" viewers="800" dvd="90" cost="40000" color="#66FF33"/> <show title="Invader Zim" hours="3" viewers="1200" dvd="124" cost="83450" color="#9933CC"/> <show title="House" hours="17" viewers="1660" dvd="132" cost="46981" color="#3311CC"/> <show title="Stargate SG-1" hours="22" viewers="870" dvd="294" cost="129350" color="#CC9933"/> <show title="Family Guy" hours="31" viewers="787" dvd="431" cost="19300" color="#3333FF"/> <show title="Futurama" hours="19" viewers="679" dvd="121" cost="17450" color="#FFFF33"/> <show title="3rd Rock" hours="11" viewers="438" dvd="41" cost="12673" color="#66CC66"/> <show title="Arrested Development" hours="8" viewers="566" dvd="133" cost="18432" color="#FF9933"/> <show title="Aqua Teen Hunger Force" hours="24" viewers="819" dvd="240" cost="8911" color="#DD4444"/> <show title="The Twilight Zone" hours="18" viewers="693" dvd="143" cost="32331" color="#662299"/> </data>
For every <dataseries/>, a pie will be drawn, and they will all be scaled to fit within the overall chart.
There's also a speed increase. It's unclear what was slowing down the old stuff so much, but in the live examples, from the initial load to any animations and zooming, everything is instantaneous in comparison.
The legends are more interactive and more attractive. With the pie charts, they're also collapsible, so that when there are multiple pies present, the legends have the capability of appearing as a kind of “thumbnail” that, when the pie is expanded, becomes a full legend. One can also click individual elements on a legend and toggle the data that's displayed. There are a few additional features that have yet to be added, but it's a good base.
Which brings us to expansibility: Unlike the older components that we currently offer, the new components have been rewritten in a more straightforward way that allows for greater expansion by both ourselves and developers. We can easily add new types of charts that use the shared components available in the charting package. And as with adding animations to bars, for instance, it'll be rather trivial to make improvements and expand visual customization options in the future.
