Graphs for FreeWX and FreeWX-Wi

This guide assumes that you are familiar with coding web pages and where appropriate updating the FreeWX template files. It further assumes that you have already downloaded jsGraphIT.

Firstly you must make the following entry in the <HEAD> section of the page on which you want to display a graph. If you are using the FreeWX templates then this entry already exists.

<SCRIPT LANGUAGE="JavaScript 1.2" TYPE="text/javascript" SRC="graph.js"></SCRIPT>.

If graph.js is not installed in the same directory as the HTML page then the SRC entry must contain the path to the file as wel as identify the file.

Note for FreeWX/FreeWX-Wi users: If you upload the new graph.js file directly to your web server, don't forget to also replace the one in your local FreeWX directory. FreeWX will upload it again to the same directory as the web pages whenever you make changes to the graph settings in FreeWX.

Additional file required for line graphs only...

If you want to be able to make line graphs then you must also download the wz_jsgraphics package from here. You must then upload this script to your web server and include reference to it in the document(s) on which you wish to display line graphs. This will involve modifying the <HEAD> section of your FreeWX templates. FreeWX will not automatically upload this file for you.

The following line...

<SCRIPT LANGUAGE="JavaScript 1.2" TYPE="text/javascript" SRC="wz_jsgraphics.js"></SCRIPT>.

...must be entered in the <HEAD> section of your html templates ABOVE the line for graph.js.

Now, in the HTML where you want a graph to appear you should follow the following instructions.

Open a script tag...

If linking to an external .js file, include the SRC (Source) file in the above and then simply close the script tag. The content of the external js file should not be enclosed in script tags.

NOTE: JavaScript is a case sensitive language. Please create parameters and settings exactly as directed below.

Invoke the Graph script... (Required)

var h = new Graph(width, height, axis color, offset, IsWind, NonMetric, time24, source, result)

e.g. var h = new Graph(400,200,'#000000',0,0,0,1,"external");

width is the width in pixels that you would like the main graph area to be.

height is the height in pixels that you would like the main graph area to be.

Note: width and height set the desired size of the area the graph 'bars' will occupy. It does not include the title, y axis label, x axis label or axis values. It is a desired size, not a fixed size. When the graph is drawn the desired size is used to calculate the width of the graph bars and the maximum and minimum heights taking into account the amount of data and variance in the data.

axis color is the color of the axis lines only. It can be either a color word or a hex color value.

offset is not used in the latest version of the file. offset is now calculated internally depending on other graph settings. Leave this at zero. It will be ignored.

IsWind MUST be set to 1 for a wind direction graph and to zero for all other types of graph.

NonMetric must be set to 1 for any graphs with non metric measurements such as rainfall in inches or a barometer in In.hg. Must be set to 0 (zero) for all other graphs.

time24 comes into play only if you are setting up a time based graph as explained below. Set to 1 if you want the X axis values to show the time on a 24 hour clock or set to 0 if you want to see a 12 hour clock with am and pm appended.

source identifies the source of the graph to maintain full compatibility with FreeWX. It should be set to "external" for all graphs created outside of FreeWX generated graph data.js files.

result is an optional parameter that if set will instruct the HTML created by the graph script to be output to a variable 'gtext' rather than drawn directly to the document. This is useful where those who understand scripting might want to position the graph data after the page is created. Omit this parameter completely from the call to Graph if you don't know how you would use it or don't need to use it. If you do want to use it, set it "1". Note that line graphs cannot be created using this method.

IMPORTANT NOTE: h is the identifier of a variable declared by the instruction var h = new Graph(). h could be any letter or word you want it to be. If you decide to set a different variable then the 'h' in the following instructions must also be changed to the new variable identifier. So, if you declared var b1 = new Graph() then the following settings would all start b1. and not h.

Add the values to be plotted... (Required)

h.addRow(value, value, value,...)

e.g. h.addRow(2.1,1.8,1.9,1.9,2.6,2.9,2.3,2.5,1.9,2.1,1.9);

h.addRow should be called for as many X axis as you want plotted on the graph. Each call is one X axis. A bar will be created for each value entered. Therefore if there are 3 values entered then only 3 bars will be created, 30 values creates 30 bars etc. If you call addRow more than once then a dual or even tripple or more graph will be created with the bars side by side. The only exception to this is a MaxMin graph as explained below where two h.addRow calls will be used together.

NOTE: h.addRow should always be the entry immediately following invoking the Graph as in (2) above.

Note for users of FreeWX/FreeWX-Wi

The latest Beta versions of FreeWX and FreeWX-Wi now output the data you need for this as a seperate web tags...

~~TEGR24DATA~~ JavaScript graph temperature data
~~HUGR24DATA~~ JavaScript graph humidity data
~~BAGR24DATA~~ JavaScript graph barometer data
~~DPGR24DATA~~ JavaScript graph dewpoint data
~~WSGR24DATA~~ JavaScript graph wind speed data
~~WDGR24DATA~~ JavaScript graph wind direction data
~~RAGR24DATA~~ JavaScript graph rainfall data
~~ITGR24DATA~~ JavaScript graph indoor temperature data
~~IHGR24DATA~~ JavaScript graph indoor humidity data

To use these you would enter on your web page, for example, the following taking note of the other settings below:

h.addRow(~~TEGR24DATA~~) would complete the required data for temperature.

Decide on the type of graph to be plotted... (1 Required)

h.setDate()
or h.setTime()
or h.setXScale()
or h.setXScaleValues()

These calls all set up the X axis of the graph. Note that you must put one and only one of these in the script. This is true even if you are creating a graph with a zero based X axis as explained below. While such a graph doesn't display X axis values, it still needs to know what to plot. The values generated by these calls are used in the graph mouseOvers as well as the X axis labels. Each of these calls has parameters associated with it and they are explained as follows:

h.setTime(hour, min, skip, inc)

Each of these parameters is numeric. hour and min are the time at which the graph should start. inc is the numbers of minutes to increment to the next bar in the graph. skip is the number of bars to skip to the next X axis label.

example: setTime(11,30,12,30) would plot a graph with the first bar at 11.30am and the next bar 30 minutes later at 12:00. There would be an X axis label every 12 bars.

Note for users of FreeWX/FreeWX-Wi

This is the correct graph type to set for the FreeWX last 24 hour graphs. You should use the hour and minute web tags...

~~JSGR24HOUR~~ JavaScript graph start time hour
~~JSGR24MINS~~ JavaScript graph start time minute

Also, you do not need to set the skip and inc because these are defaulted in jsGraphIT to the required 12 and 30 respectively.

So for each graph in which you are using the FreeWX output data you shoudl set this line as follows...

h.setTime(~~JSGR24HOUR~~, ~~JSGR24MINS~~)

h.setDate(Day, Month, Year, skip, inc)

Each of these parameters is numeric. Day, Month and Year are the date on which the graph should start. inc is the numbers of days to increment to the next bar in the graph. skip is the number of bars to skip to the next X axis label.

example: setDate(11,2,2005,7,1) would plot a graph starting on 11 Feb 2005 incrementing by day with the labels every 7 days.

h.setXScale(start, skip, inc)

Each of these parameters is numeric. start is the value at which you want the graph to start. inc is the amount to increment to the next bar and skip is the number of bars to skip to the next X axis label.

example: setXScale(10,10,10) would plot a graph with the first X axis label as 10, the next as 20 etc. Labels would be displayed every 10 bars.

h.setXScaleValues(1, 2, 3, 4, 5...... or "fred, john, bill, ted.....")

Each of these parameters can be numeric or a sting but not both mixed. If you want both mixed then use a string containing numeric entries. There should be a value, seperated by commas for every value you are plotting in (3) above. If you need to change the X axis labels to skip some then use h.skip as directed below.

Optional Settings... (Optional)

These settings can be added where needed but are not required in order to plot a graph. It doesn't matter what sequence these are placed in providing they follow the above (Required) entries and are before the call to Build() explained below.

If you don't require one of these settings simply leave it out.

Setting	Type	Explanation
h.title = ""	String	This is the title for the graph.
h.xLabel = ""	String	X axis label to appear under the graph.
h.yLabel = ""	String	Y axis label to appear on the left of the graph.
h.inc =	Integer	Overides the inc (increment) set in the graph type declarations above.
h.skip =	Integer	Overides the skip set in the graph type declarations above. Can also be useful with setXScaleValues when you want to skip certain values on the X axis labels.
h.showDay = 1	1	Only of any use with a setDate() graph. Instructs the mouseOver info and X axis labels to include the abbreviated day. e.g. Mon, Tue... etc.
h.showYear = 1	1	Only of any use with a setDate() graph. Instructs the mouseOver info and X axis labels to include the year. This will be shown as a single or double digit unless longYear is set to 1 below.
h.longYear = 1	1	Only of any use with a setDate() graph. Instructs the mouseOver info and X axis labels to include the full 4 digit year.
h.longDate = 1	1	Only of any use with a setDate() graph. Instructs the mouseOver info and X axis labels to include the full date including the abbreviated month. e.g. Mon 21-Jan-2006.
h.MaxMinGraph = 1	1	Instructs the graph to be formed as a MinMax graph with bars floating between the minimum and maximum values. For this to work there must be and can be only 2 addRow calls as explained above. One for the maximum values and one for the minimum values.
h.negbars = 1	1	Instructs the graph to be formed with a zero based X axis. No X axis labels will be shown on such a graph but any -ve value bars will be shown below the X axis.
h.bgColor = ""	String	Sets a background color for the entire graph. Can either be color words or hex values.
h.setLegend("","",...)	String	Sets a legend for the graph if plotting more than one set of values and not a MaxMin graph. The entries in this should match the number of times addRow has been called. e.g. if you've called addRow twice then this would look something like... h.setLegend("Value 1","Value 2")
h.setBarcolors("","",...)	String(s)	Sets the colours to use for the bars. Can contain multiple entries. Each entry will be used in sequence for the number of values being plotted. eg. h.setBarcolors("#FF0000") or h.setBarcolors("Red"). Note: Instead of colors this entry can also contain references to image files. This though is really for backwards compatibility with current FreeWX graphs and is not recommended for performance reasons.
h.setNegcolors("","",...)	String(s)	As above except for bars appearing below a zero based X axis.
h.setTitles("","","")	Strings	Sets the font, font size and color of the title, Y label and X label. Being for the web, multiple values can be set for the font and the browser will use them in order of preference. e.g. h.setTitles("Tahoma","10","#009900"). NOTE the font size is a true point font size not old HTML -/+ settings.
h.setAxis("","","")	Strings	As above but for the X and Y axis labels. e.g. h.setAxis("Tahoma","10","#FF0000")
h.setWindoptions(1,1,1,"")	Mixed	Only of any use if it is a wind direction graph being plotted (i.e. IsWind is set to 1 in the parameters of the call to Graph as explained above). The parameters are as follows: The first parameter if set to 1 instructs the Y degree labels to be replaced with N, NE, E etc. The second parameter if set to 1 instructs the graph to be drawn with lines instead of bars. The third parameter is the size in pixels of the lines and the last parameter is the colour to use for the lines. e.g. h.setWindoptions(1,1,1,"#ABC123") or h.setWindoptions(1,1,1,"bar5.gif") If the call is needed but you want to turn off the compass points (leave at default degrees) then set the first parameter to -1. If you want to have bars and not lines then set the second parameter to -1.
h.gBorder = X	Integer	Places a border of X pixels around the entire graph.
h.setPosStyle = ""	String	Standard style tag for setting the style of bars above the X axis. Must end in a semi colon.
h.setMidStyle = ""	String	As above but for bars that 'float' in a MaxMin graph.
h.setNegStyle = ""	String	As above but for bars below a zero based negative axis.
h.g3d = ""	in or out	Sets a 3D effect border around the bars which can be set to make the bars appear to stand out from the page or to be set into it. e.g. h.g3d = "in".
h.gGrid = ""	String	Switches on horizontal grid lines to assist with visual alignment of bars with lines of the colour set. e.g. h.gGrid = "#777777" or h.gGrid = "Blue".
h.gBorderWidth = ???	Integer	Allows a frame formed around the graph by gBorder or bgColor to have a fixed width in pixels providing it is bigger than the graph being formed. If it is smaller, the graph will push it to a larger size to accommodate it. e.g. h.gBorderWidth = 600
h.setLines("",2)	Mixed	Instructs the graph to draw as continuous lines in place of bars. Note: In order for this function to work you must also have installed wz_jsgraphics.js and correctly called it in the <HEAD> of your HTML page as directed above. The first parameter of this call is the ID for the graph. Each graph should have a unique ID. This is simply a name that is different from any other name or style ID on your page. The second parameter is the size of the lines you want drawn. e.g. h.setLines("linegraph1",2) Please note this setting has no effect on the wind direction graph if it is set using the setWindoptions setting above and it should not be used with any graph set as a MaxMin graph.
h.shownegscale = 1	Ineger	When set instructs a graph set to show negative values below a zero X axis to also show the X axis scale and values 10 pixels below the graph.

Build the graph... (Required)

h.build()

This entry must be at the end of the script before the closing script tag otherwise nothing will be output to the browser.

Close the script tag if needed...

</SCRIPT>

Example...