ProtoChartVersion: v0.5 beta ProtoChart is a charting lib on top of Prototype. This library is heavily motivated by excellent work done by: Complete examples can be found at: http://www.deensoft.com/lab/protochart Summary | | | | | Description: Various options can be set. | | | | | | | | | | {Object} needle {Object} haystack | | Description: sets the bar width for Bar Graph, you should enable autoScale property for bar graph | | Description: Private function that goes through each graph data (series) and assigned the graph properties to it. | | Description: processes graph data, setup xaxis and yaxis min and max points. | | Description: constructs the main canvas for drawing. | | Description: a container function that does a few interesting things. | | {Object} axis {Object} axisOptions | | {Object} axis {Object} axisOptions | | | | {Object} axis {Object} axisOptions | | | | | | | | | | | | | | | | {Object} data {Object} offset | | | | | | {Object} data {Object} radius {Object} fill | | {Object} data {Object} offset {Object} radius | | | | | | {Object} anchorX {Object} anchorY {Object} radius | | | | {Object} graphData {Object} barDataRange | | | | {Object} graphData {Object} data {Object} barWidth {Object} offset {Object} fill {Object} counter {Object} total {Object} barDataRange | | {Object} graphData {Object} orgStrokeStyle {Object} left {Object} bottom {Object} top {Object} right {Object} drawLeft {Object} drawRight {Object} drawTop | | {Object} graphData {Object} counter {Object} total {Object} barDataRange | | inserts legend onto the graph. | | | | | | | | Internal function called when a selection on the graph is made. | | | | Description: Internal function called to draw the selection made on the graph. | | | | | | | | | | Helper class that manipulates colors using RGBA values. |
optionsDescription: Various options can be set. More details in description. colors| {Array} | pass in a array which contains strings of colors you want to use. Default has 6 color set. |
legend| {BOOL} | show - if you want to show the legend. Default is false | | {integer} | noColumns - Number of columns for the legend. Default is 1 | | {function} | labelFormatter - A function that returns a string. The function is called with a string and is expected to return a string. Default = null | | {string} | labelBoxBorderColor - border color for the little label boxes. Default #CCC | | {HTMLElem} | container - an HTML id or HTML element where the legend should be rendered. If left null means to put the legend on top of the Chart | | {string} | position - position for the legend on the Chart. Default value ‘ne’ | | {integer} | margin - default valud of 5 | | {string} | backgroundColor - default to null (which means auto-detect) | | {float} | backgroundOpacity - leave it 0 to avoid background |
xaxis (yaxis) options| {string} | mode - default is null but you can pass a string “time” to indicate time series | | {integer} | min | | {integer} | max | | {float} | autoscaleMargin - in % to add if auto-setting min/max | | {mixed} | ticks - either [1, 3] or [[1, “a”], 3] or a function which gets axis info and returns ticks | | {function} | tickFormatter - A function that returns a string as a tick label. Default is null | | {float} | tickDecimals | | {integer} | tickSize | | {integer} | minTickSize | | {array} | monthNames | | {string} | timeformat |
Points / Lines / Bars options| {bool} | show, default is false | | {integer} | radius: default is 3 | | {integer} | lineWidth : default is 2 | | {bool} | fill : default is true | | {string} | fillColor: default is #ffffff |
Grid options| {string} | color | | {string} | backgroundColor - defualt is null | | {string} | tickColor - default is #dddddd | | {integer} | labelMargin - should be in pixels default is 3 | | {integer} | borderWidth - default 1 | | {bool} | clickable - default null - pass in TRUE if you wish to monitor click events | | {mixed} | coloredAreas - default null - pass in mixed object eg. {x1, x2} | | {string} | coloredAreasColor - default #f4f4f4 | | {bool} | drawXAxis - default true | | {bool} | drawYAxis - default true |
selection options| {string} | mode : either “x”, “y” or “xy” | | {string} | color : string |
setData{Object} data DescriptionSets datasoruces properly then sets the Bar Width accordingly, then copies the default data options and then processes the graph data Returns: none parseData| parseData: function( | data | ) |
|
{Object} data Return{Object} result DescriptionTakes the provided data object and converts it into generic data that we can understand. User can pass in data in 3 different ways: - [d1, d2]
- [{data: d1, label: “data1”}, {data: d2, label: “data2”}]
- [d1, {data: d1, label: “data1”}]
This function parses these senarios and makes it readable makeRandomColor| makeRandomColor: function( | colorSet | ) |
|
{Object} colorSet Return| {Array} result | array containing random colors |
checkExisted| checkExisted: function( | needle, | | haystack | ) |
|
{Object} needle {Object} haystack return| {bool} existed | true if it finds needle in the haystack |
setBarWidthDescription: sets the bar width for Bar Graph, you should enable autoScale property for bar graph copyGraphDataOptions| copyGraphDataOptions: function() |
Description: Private function that goes through each graph data (series) and assigned the graph properties to it. processGraphData| processGraphData: function() |
Description: processes graph data, setup xaxis and yaxis min and max points. constructCanvas| constructCanvas: function() |
Description: constructs the main canvas for drawing. It replicates the HTML elem (usually DIV) passed in via constructor. If there is no height/width assigned to the HTML elem then we take a default size of 400px (width) and 300px (height) setupGridDescription: a container function that does a few interesting things. 1. calls extendXRangeIfNeededByBar function which makes sure that our axis are expanded if needed 2. calls setRange function providing xaxis options which fixes the ranges according to data points 3. calls prepareTickGeneration function for xaxis which generates ticks according to options provided by user 4. calls setTicks function for xaxis that sets the ticks similar sequence is called for y-axis. At the end if this is a pie chart than we insert Labels (around the pie chart) via insertLabels and we also call insertLegend setRange| setRange: function( | axis, | | axisOptions | ) |
|
parameters{Object} axis {Object} axisOptions prepareTickGeneration| prepareTickGeneration: function( | axis, | | axisOptions | ) |
|
Parameters{Object} axis {Object} axisOptions extendXRangeIfNeededByBar| extendXRangeIfNeededByBar: function() |
setTicks| setTicks: function( | axis, | | axisOptions | ) |
|
parameters{Object} axis {Object} axisOptions translateHoz| translateHoz: function( | x | ) |
|
Paramters{Object} x Description: Given a value this function translate it to relative x coord on canvas translateVert| translateVert: function( | y | ) |
|
parameters{Object} y Description: Given a value this function translate it to relative y coord on canvas drawGridparameters: none description: draws the actual grid on the canvas insertLabelsparameters: none description: inserts the label with proper spacing. Both on X and Y axis drawGraph| drawGraph: function( | graphData | ) |
|
Paramters{Object} graphData Description: given a graphData (series) this function calls a proper lower level method to draw it. plotLine| plotLine: function( | data, | | offset | ) |
|
parameters{Object} data {Object} offset descriptionHelper function that plots a line based on the data provided plotLineArea| plotLineArea: function( | data | ) |
|
parameters{Object} data descriptionHelper functoin that plots a colored line graph. This function takes the data nad then fill in the area on the graph properly drawGraphLines| drawGraphLines: function( | graphData | ) |
|
parameters{Object} graphData descriptionMain function that daws the line graph. This function is called if options lines property is set to show or no other type of graph is specified. This function depends on plotLineArea and plotLine functions. plotPoints| plotPoints: function( | data, | | radius, | | fill | ) |
|
parameters{Object} data {Object} radius {Object} fill descriptionHelper function that draws the point graph according to the data provided. Size of each point is provided by radius variable and fill specifies if points are filled plotPointShadows| plotPointShadows: function( | data, | | offset, | | radius | ) |
|
parameters{Object} data {Object} offset {Object} radius descriptionHelper function that draws the shadows for the points. drawGraphPoints| drawGraphPoints: function( | graphData | ) |
|
paramters{Object} graphData descriptionDraws the point graph onto the canvas. This function depends on helper functions plotPointShadows and plotPoints preparePieData| preparePieData: function( | graphData | ) |
|
parameters{Object} graphData DescriptionHelper function that manipulates the given data stream so that it can be plotted as a Pie Chart drawPieShadow| drawPieShadow: function( | anchorX, | | anchorY, | | radius | ) |
|
{Object} anchorX {Object} anchorY {Object} radius descriptionHelper function that draws a shadow for the Pie Chart. This just draws a circle with offset that simulates shadow. We do not give each piece of the pie an individual shadow. drawPieGraph| drawPieGraph: function( | graphData | ) |
|
parameters{Object} graphData descriptionDraws the actual pie chart. This function depends on helper function drawPieShadow to draw the actual shadow drawBarGraph| drawBarGraph: function( | graphData, | | barDataRange | ) |
|
parameters{Object} graphData {Object} barDataRange descriptionGoes through each series in graphdata and passes it onto drawBarGraphs function drawGraphBar| drawGraphBar: function( | graphData | ) |
|
parameters{Object} graphData descriptionThis function is called when an individual series in GraphData is bar graph and plots it plotBars| plotBars: function( | graphData, | | data, | | barWidth, | | offset, | | fill, | | counter, | | total, | | barDataRange | ) |
|
parameters{Object} graphData {Object} data {Object} barWidth {Object} offset {Object} fill {Object} counter {Object} total {Object} barDataRange descriptionHelper function that draws the bar graph based on data. plotShadowOutline| plotShadowOutline: function( | graphData, | | orgStrokeStyle, | | left, | | bottom, | | top, | | right, | | drawLeft, | | drawRight, | | drawTop | ) |
|
parameters{Object} graphData {Object} orgStrokeStyle {Object} left {Object} bottom {Object} top {Object} right {Object} drawLeft {Object} drawRight {Object} drawTop descriptionHelper function that draws a outline simulating shadow for bar chart drawGraphBars| drawGraphBars: function( | graphData, | | counter, | | total, | | barDataRange | ) |
|
parameters{Object} graphData {Object} counter {Object} total {Object} barDataRange descriptionDraws the actual bar graphs. Calls plotBars to draw the individual bar insertLegenddescriptioninserts legend onto the graph. legend: {show: true} must be set in options for for this to work. onMouseMove| onMouseMove: function( | ev | ) |
|
parametersevent: {Object} ev DescriptionCalled whenever the mouse is moved on the graph. This takes care of the mousetracking. This event also fires <ProtoChart:mousemove> event, which gets current position of the mouse as a parameters. onMouseDownParametersDescriptionCalled whenever the mouse is clicked. onClickparameters| Event | {Object} e Description: Handles the “click” event on the chart. This function fires <ProtoChart:plotclick> event. If <options.allowDataClick> is enabled then it also fires <ProtoChart:dataclick> event which gives you access to exact data point where user clicked. |
triggerSelectedEvent| triggerSelectedEvent: function() |
DescriptionInternal function called when a selection on the graph is made. This function fires <ProtoChart:selected> event which has a parameter representing the selection { x1: {int}, y1: {int}, x2: {int}, y2: {int} } setSelection| setSelection: function( | area | ) |
|
Parameters| Area | {Object} area represented as a range like: {x1: 3, y1: 3, x2: 4, y2: 8} |
DescriptionSets the current graph selection to the provided range. Calls drawSelection and triggerSelectedEvent functions internally. drawSelection| drawSelection: function() |
Description: Internal function called to draw the selection made on the graph. hit| hit: function( | event, | | mouse | ) |
|
Parameters| event | {Object} event object | | mouse | {Object} mouse object that is used to keep track of mouse movement |
DescriptionIf hit occurs this function will fire a ProtoChart:hit event. extractColor| extractColor: function( | element | ) |
|
Parameters| element | HTML element or ID of an HTML element |
Returnscolor in string format parseColor| parseColor: function( | str | ) |
|
Parameters| str | color string in different formats |
Returns| a Proto.Color Object | use toString() function to retreive the color in rgba/rgb format |
Proto. ColorHelper class that manipulates colors using RGBA values. |