BARCHART - AppDaddy-Software-Solutions-Inc/framework-markup-language GitHub Wiki

The BARCHART framework element displays a graphical representation of a dataset.

The BARCHART outputs a graph displaying X and Y data points in a range of visual configurations.

The y axis (sometimes referred to as the measure axis, usually vertical) must be numeric

Requires both an XAXIS and a YAXIS child

Requires SERIES child(ren)

• XAXIS/YAXIS
• LABEL
• SERIES

The SERIES outputs a dataset plotting its X and Y data points within a CHART element. It has multiple settings to configure how it graphs the visual data for both cartesian and pie charts. When using multiple series within a cartesian chart they will be placed as layers with the first SERIES being the bottom layer and the last SERIES being the top layer. Aside from some restrictions you can use multiple SERIES in the same CHART and the SERIES type can be mixed as well, for example you could have a line series over a bar series.

• Choose a series type that best displays the type of information supplied as a whole for all the series, or combine two types that show alternate data that correlates to each other. Be aware of which series will work together.
• Use a series type that fits the space of your graph and data, series with more data or labels should use less intrusive graphing styles to leave room for labels and small series should use larger styles to enhance readability of the data.
• Ambiguity should be kept to a minimum through legends and labels
• Be conscious your data is visible with the ordering of series layers and place label series types last so they overlay the series they are mapping.
• Consider using a custom TOOLTIP for labels that are too big.
• Name each series so it can be clearly displayed in the legend.

• A pie chart type CHART can only have a single SERIES child
• A bar chart type can only have multiple series if each series defines how to stack and/or group them together
• The y value(s) must be a numeric data type
• SERIES requires an assigned data attribute to reference and plot data
• If the XAXIS is a type of time and there is multiple bar series, they cannot be stacked, only grouped.
• If the XAXIS is a type of time and you have a bar series it is not possible to show labels.

The XAXIS/YAXIS are required children of CHART, it conveys the scope of the data within the chart to the user by giving visual control over how SERIES data is plotted in relation to the axes.

• Use labelrotation on the XAXIS when you have longer labels, recommended value being between -90(vertical) and -30. See (examples).

YAXIS must be numeric type="numeric". XAXIS with a type of date / time / datetime must have datetime ISO 8601 formatted point data (ie: 2021-11-21T21:21:21) See examples.

LABELs are optional children of CHART, they draw a label on the chart, it serves the purpsoe of annotating a point or range from the chart axis. If you supply a range on an axis it will can highlight the range, it can also be used to add additional information about a chart AXIS.

• Use LABELs to highlight an section of the chart or to add additional axis information, they can be derived from a databroker like axis ticks which can be useful for providing more information along an axis.

A label is axis bound and can only contain plot values for x or x1 + x2 or y or y1 + y2.

You can bind to the selected point data which updates each time a user selects a new data point by: {mychartid.selected.mydatafieldkeyfromadatasource}

You can also bind to point values with {mychartid.selected._id/_x/_y/_label} as long as the name doesn't collide with the datasource data keys.

<DATA id="DB1">
    <VALUE>
        <![CDATA[<SET>
            <COORD>
                <x>1</x> <x2>January</x2> <x3>2010-07-20 20:18:04Z</x3> <y>3</y> <y2>1</y2>	
            </COORD>
            <COORD>
                <x>2</x> <x2>February</x2> <x3>2011-07-20 20:18:04Z</x3> <y>5</y> <y2>3</y2>
            </COORD>
            <COORD>
                <x>3</x> <x2>March</x2> <x3>2012-07-20 20:18:04Z</x3> <y>4</y> <y2>2</y2>
            </COORD>
            <COORD>
                <x>4</x> <x2>April</x2> <x3>2013-07-20 20:18:04Z</x3> <y>8</y> <y2>6</y2>
            </COORD>
            <COORD>
                <x>5</x> <x2>May</x2> <x3>2014-07-20 20:18:04Z</x3> <y>7</y> <y2>9</y2>
            </COORD>
            <COORD>
                <x>6</x> <x2>June</x2> <x3>2015-07-20 20:18:04Z</x3> <y>7</y> <y2>5</y2>
            </COORD>
            <COORD>
                <x>7</x> <x2>July</x2> <x3>2016-07-20 20:18:04Z</x3> <y>10</y> <y2>8</y2>
            </COORD>
            <COORD>
                <x>8</x> <x2>August</x2> <x3>2017-07-20 20:18:04Z</x3> <y>11</y> <y2>13</y2>
            </COORD>
            <COORD>
                <x>9</x> <x2>September</x2> <x3>2018-07-20 20:18:04Z</x3> <y>10</y> <y2>8</y2>
            </COORD>
            <COORD>
                <x>10</x> <x2>October</x2> <x3>2019-07-20 20:18:04Z</x3> <y>9</y> <y2>7</y2>
            </COORD>
            <COORD>
                <x>11</x> <x2>November</x2> <x3>2020-07-20 20:18:04Z</x3> <y>11</y> <y2>9</y2>
            </COORD>
            <COORD>
                <x>12</x> <x2>December</x2> <x3>2021-07-20 20:18:04Z</x3> <y>14</y> <y2>12</y2>
            </COORD>
        </SET>]]>
    </VALUE>
</DATA>

All figures shown below are derived from this data for consistency.

<CHART id="testchart" type="pie" showlegend="bottom">
	<XAXIS type="category" title="Month" />
	<YAXIS type="numeric" title="Amount" />
	<SERIES name="Pie Series 1" type="pie" data="DB1" x="{data.x2}" y="{data.y2}" label="${data.y2}" />
</CHART>

See it in Action

<CHART id="examplechart" showlegend="true">
	<XAXIS type="category" title="Month" />
	<YAXIS type="numeric" title="Amount" />
	<SERIES id="ls1" name="Line Series 1" type="line" data="DB1" x="{data.x2}" y="{data.y2}" color="cyan" stroke="2" showarea="true" showpoints="false" />
	<SERIES id="ls2" name="Line Series 2" type="line" data="DB1" x="{data.x2}" y="={data.y} - 1" color="orange" stroke="4.5" radius="5"/>
	<SERIES id="ls3" name="Line Series 3" type="line" data="DB1" x="{data.x2}" y="={data.y} - 1" color="={data.y} &lt; {data.y2} ? 'red' : 'white'" showline="false" radius="3.5"/>
</CHART>

See it in Action

	<CHART id="examplechart" showlegend="false">
		<XAXIS type="time" format="yyyy/MM/dd" title="Date"/>
		<YAXIS type="numeric" title="Amount" />
		<SERIES id="s1" name="Bar Series 1" group="1" type="bar" data="DB1" x="{data.x3}" y="{data.y}" color="lightblue" />
	</CHART>

See it in Action

<CHART id="examplechart" showlegend="true">
	<XAXIS type="numeric" title="Month" />
	<YAXIS type="numeric" title="Amount" />
	<SERIES name="Bar Series 1" type="bar" data="DB1" x="={data.x} - 1" y="{data.y}" color="cyan" stroke="1" />
	<SERIES id="ls1" name="Line Series 1" type="line" data="DB1" x="={data.x} - 1" y="{data.y2}" color="red" stroke="2" showarea="true" showpoints="false" />
</CHART>

See it in Action

<CHART id="examplechart" showlegend="false">
	<XAXIS type="time" format="yyyy/MM/dd" title="Date" labelrotation="-45" />
	<YAXIS type="numeric" title="Amount" />
	<SERIES id="s1" name="Bar Series 1" group="1" type="bar" data="DB1" x="{data.x3}" y="{data.y}" color="lightblue" />
	<SERIES id="s2" name="Bar Series 2" group="1" type="bar" data="DB1" x="{data.x3}" y="{data.y2}" color="blue" />
</CHART>

See it in Action

<CHART id="examplechart" showlegend="true">
	<XAXIS type="category" format="yyyy/MM/dd" title="Date" labelrotation="-45" />
	<YAXIS type="numeric" title="Amount" />
	<SERIES id="s1" name="Bar Series 1" stack="1" type="bar" data="DB1" x="{data.x2}" y="{data.y}" color="lightblue" label="{data.y}" labeled="true" />
	<SERIES id="s2" name="Bar Series 2" stack="1" type="bar" data="DB1" x="{data.x2}" y="{data.y2}" color="blue" label="{data.y2}" labeled="true" />
</CHART>

See it in Action

<CHART id="examplechart" showlegend="true">
	<XAXIS type="category" title="Month" />
	<YAXIS type="numeric" title="Amount" />
	<SERIES stack="1" group="3" name="Bar Series 1" type="bar" data="DB1" x="{data.x}" y="{data.x}" color="blueaccent" stroke="1" />
	<SERIES stack="1" group="3" name="Bar Series 2" type="bar" data="DB1" x="{data.x}" y="{data.y}" color="blue" stroke="1" />
	<SERIES stack="1" group="3" name="Bar Series 3" type="bar" data="DB1" x="{data.x}" y="{data.y2}" color="lightblue" stroke="1" />
	<SERIES stack="2" group="4" name="Bar Series 4" type="bar" data="DB1" x="{data.x}" y="=({data.x} - 1) * 2" color="teal" stroke="1" />
	<SERIES stack="2" group="4" name="Bar Series 5" type="bar" data="DB1" x="{data.x}" y="={data.y} - {data.y2} + 2" color="green" stroke="1" />
	<SERIES stack="2" group="4" name="Bar Series 6" type="bar" data="DB1" x="{data.x}" y="{data.y2}" color="lightgreen" stroke="1" />
</CHART>

See it in Action

• XAXIS/YAXIS
• SERIES