In order to display graphs in your document with this utility, you must include lines like the following within the <HEAD> and </HEAD> tags in the top of your document:
Of course Your_JavaScript_Url could (right now) be replaced by http://www.clange.dk/~cl/clGraph, but that is probably neither efficient nor reliable for very long. And maybe my internet provider would dislike it too - even though I believe that it should not require that much bandwidth on the network nor other resources.
In order to use Your_JavaScript_Url you must get the files clGrSets.js, clGraph.js, clGrWr.js, clGrStyl.css and also the file 1x1_tr.gif . Even though reluctantly, I have made the files available in this zip-file
You supply input data for graphs by entering the data as the values of INPUT elements in a FORM (or in several FORMs if you want to show several graphs on the same page) included in the HTML document where you want to show the graph(s). The INPUT lines must follow the format:
NOTICE: That the Attribute Field Names must be written exactly as in this document - also when it comes to the capitalization! No fault messages or warnings will be given due to misspelling or erroneous capitalization. Such INPUT elements will simply be ignored.
NOTICE: That only an absolutely minimum of sanity checks are performed. Erroneous data might generate JavaScript execution errors, or just cause the display of the graph to be faulty.
The order in which the INPUT elements occur in the FORM is totally insignificant. It is the FieldNames and YourData that matters alone!
The FORM containing the the INPUT elements with data and specifications of non-default graph attributes, as descibed below, must be given a name like in this example:
At the place in your document where you want to display the graph you must enter a piece of HTML code like the following:
The HTML code between the <NOSCRIPT> and </NOSCRIPT> tags tell readers who have JavaScript disabled in their browser preferences or who uses a browser not capable of executing JavaScript, that they are missing something, and is not a part of this utility. Thus you can change these lines as you like.
The actual data to visualize must be entered with INPUT elements with the following format:
The first column to the left of the rn-lines always relates to the X-axis, and each of the following columns concerns a specific series of data.
The first column of the first row (r1) will be used as Title for the X-axis and each of the following columns will be used as Legend text for a dataseries.
For each of the following rows (r2 - rmax) the first column will be taken as a X-axis value (text) and each following column must be either empty or hold a numerical data value for that dataseries.
Thus the absolutely most simple form of a bar graph, must have two lines with two columns:You can change the appearence of a graph by specifying certain attributes for the different elements of the graph. This is done by adding lines with INPUT to the FORM also containing the data for the graph.
In the following the different attributes you can modify will be described. The descriptions might also include things to come - or just plain wishfull thinking. I'll try to make it clear what can be used now, and what can not!
The URL to an image (.GIF or .JPG) to use as background image. This image will shine through all other areas of the graph, without a backgground color or image specification.
Since this background image is used as attribute to a HTML TABLE tag, the image will be replicated for each table cell within that table. The main table of the graph has three separate cells:
You can specify any valid HTML URL. Default is not to use a background image.
Example of specifying a graph background image:
The background color used for the whole chart. This is really a background color assigned to the table containing the table structure with the chart.
This color will shine through all other areas of the graph, without a backgground color (or image) specification.
Example of specifying a graph background color:
DataseriesNumber attributes may be used to change the (background) color used for the bars belonging to the dataseries.
You can specify any valid HTML color value. Default is not to set any background color, except for the Plotarea which will be lightgrey by default.
For the first 10 dataseries found in data the default colors are:
There are no borders around the bars, so if a dataseries color is identical to the plotarea color (which is lightgrey by default) then the dataseries will be invisible.
Example: Setting non-default color of dataseries #1 bars:
May be used to change the order in which the dataseries are shown in the graph. Or to specify which dataseries to show in the graph, and thus omitting other dataseries.
Must be specified as a string of numbers including all dataseries to be shown in the graph. The numbers must be delimited by ',' or ' ' (space) or ', ' (comma and space). By default all datseries are shown, and the bars for dataseries #1 are shown as the leftmost bar for each value of X. If using stacked bars dataseries #1 are shown as the topmost bar for each value of X.
If DataseriesOrder is specified and not all dataseries numbers are included, then the dataseries not included will not be displayed, but they will still be included when calculating height and width of plotarea and bars. Specifying (superfluous) numbers of dataseries for which there are no columns in the "rn" input lines, may cause unpredicted errors!
Example: Switching the display order of dataseries #1 and #2 in a graph with three dataseries:
Example: Omitting the display of dataseries #2 in a graph with three dataseries:
The outer height of the graph area
As default no height is specified for the graph area. (I.e. it will scale to fit the rest of the elements of the graph.
Example of specifying the total height of the graph:
With Legend... attributes you may set the background, font, and text alignment used for displaying the list of legends, and also the number of columns OR rows used when listing.
The legend text used for each dataseries are taken from the appropriate column of the "r1" input row. These text strings CAN'T be changed by using the Legend attribute!
All Legend Title attributes are using corresponding browser/document defaults as default.
Default is to show the list of legends at the bottom of the graph area. Trying to specify another LegendLocation is not allowed.
Setting Height and Width for the legend area has not yet been implemented.
Actually the list of legends is a table of it's own - as default each different legend is shown on a separate line. Long legend texts will not wrap around, as you might normally expect, but is more likely to cause the width of the graph to be pulled out of proportions. Use shorter legend texts to prevent this from happening. You can use the LegendColumns or LegendRows attributes to modify the number of columns and rows in the table with legends.
Example of specifying horizontal alignment, background color, text color, and font size used for the list of legends:
This is the area of the graph where the bars, visualizing the data values you supplied, are shown.
If specified the PlotareaWidth AND the PlotareaHeight must be absolute (in pixels/dots). Relative values like 50% are not allowed!
The default background color of the plotarea is lightgrey.
The default height of the plotarea is 200 pixels.
The default width of the plotarea is adjusted to be close to 400 pixels. The adjustment is made so that all bars are equally wide.
If you specify a PlotareaWidth this will be the exact width of the Plotarea. In this case there might be small variations in the width of the bars.
Example of changing the default width and the default background color of the plotarea:
A title to be used as title for the graph.
If you do not specify a title, there will be no title for the graph!
Default horizontal alignment of the graph title is center.
Default is to use FontSize "+2" for the graph title.
Default is to use Bold style for the graph title.
Setting Height and Width for the graph title area has not yet been implemented.
For now the width of the graph title area is the same thing as the width of the whole graph area.
Example of specifying the title for a graph and the font family for this title:
If you assign the value Stacked Bars to Type, the bars for each dataseries will be stacked on top of each other - or rather below of each other, since the first dataseries (the leftmost column of data values in the data INPUT elements) will be shown uppermost in the stack of bars).
The default type of graph is a bargraph that shows one bar for each dataseries beside each other for each and every X-value.
The outer width of the graph area
As default no width is specified for the graph area. (I.e. it will scale to fit the rest of the elements of the graph.
For now the width of the whole graph area is the same thing as the width of the graph title area.
Example of specifying the total width of the graph:
Xaxis... attributes can be used to change the title (text, font, alignment, etc.) used for the Xaxis, the font used for tick labels along the X-axis, and or the number of x-values shown between each tick label along the X-axis.
The text used as X-axis Title are taken from the leftmost column of the "r1" input row, but may be changed by using the XaxisTitle attribute!
Default horizontal alignment for the X-axis Title is "right".
Default is to make a tick label (and tick mark) for every X-value found in the input data. (I.e. XaxisSkip defaults to 0 (zero).
All other Xaxis... attributes are using corresponding browser/document defaults as default.
Default is to show the X-axis at the bottom of the graph area. Trying to specify another XaxisLocation is not yet implemented.
Setting Height and Width for the X-axis Title area has not yet been implemented.
For now the width of the X-axis Title area is the same thing as the width of the plotarea.
X-axis tick labels can easily pull the graph out of scale horizontally. It is up to the author of the document where the JS Graphing Utility is used to adjust the font used for tick-labels, as well as the x-values supplied in the leftmost column of the data rows (or the plotarea width), so that the horizontal scaling is acceptable.
Example of changing horizontal alignment, font size, and fontstyle for the X-axis title, and also the font size used for X-axis tick labels:
Specifies the space between bars from each x-value relative to the horizontal space available per x-value.
Must be a number (integer or with decimals) between 0 and 40. Default value is 15.
The number is taken as percentage of space relative to the horizontal space available per x-value to reserve for margin both to the left and to the right of the bars belonging to the same x-value. I.e. an XaxisMargin of 40 means only 20% of the horizontal space will be available for displaying bars.
If this doesn't allow for minimum one pixel per bar to be displayed
Example: Setting Xaxis margin to 25% of the horizontal space per x-value (leaving 100% minus 2 x 25% = 50% of the space to bars)
Yaxis... attributes can be used to change the title (text, font, alignment, etc.) used for the Yaxis, the font used for tick labels along the Y-axis, the number of tick labels along the Y-axis, and the range of Y-values shown.
If you do not specify an Y-axis title, there will be no title on the Y-axis!
Default horizontal alignment of the Y-axis title is Right.
Default vertical alignment of the Y-axis title is Top.
All font attributes concerning the Y-axis are using corresponding browser/document defaults as default.
Setting Height and Width for the Y-axis title area has not yet been implemented.
For now the height of the Y-axis title area is the same thing as the height of the plotarea.
Consequences. Other comments.
Example of changing font size, fontstyle, and vertical alignment for the Y-axis title, and also the font size used for Y-axis tick labels:
Specifies the horizontal alignment within an area.
Valid values are left, center, and right.
The default value depends on the area having this attribute
| Graph Title | Default is Center |
|---|---|
| Y-axis and X-axis Titles | Default is Right |
| Legend list | Uses document/browser default (which always is Left as far as I know). |
Specifies the vertical alignment within an area.
Valid values are baseline, bottom, middle, and top.
Default is Top for the Y-axis Title. All other areas uses the document/browser default.
The URL to an image (.GIF or .JPG) to use as background image for the area.
NOTICE: Usage of background images has not been tested.
The background color used for the area.
Specifies the height of the Area.
You can specify any valid HTML height (i.e. height in pixels or in % of the enclosing element. Default is not to set any specific area height.
If the specified height is too small to hold the elements inside the area, then the area will get the minimum height required for the contained elements.
Specifies the width of the area.
You can specify any valid HTML width (i.e. width in pixels or in % of the enclosing element. Default is not to set any specific area width.
If the specified width is too small to hold the elements inside the area, then the area will get the minimum width required for the contained elements.
The URL to an image (.GIF or .JPG) to use as background image for an area. The area will either be a complete table, or a single table cell.
If the background image is used as attribute to a HTML TABLE tag, the image will be replicated for each table cell within that table.
You can specify any valid HTML URL. Default is not to use a background image. The background color used for the whole chart. This is really a background color assigned to the table containing the table structure with the chart.
The background color used for an area. The area will either be a complete table, or a single table cell.
You can specify any valid HTML color value. Default is not to set any background color, except for the Plotarea which will be lightgrey by default.
Specifies the forground/text color.
You can specify any valid HTML color value. Default is to use the browser default text color.
Specifying a FontColor will cause the text to be enclosed in <FONT COLOR=yourcolor[ Possible other font attributes]></FONT> HTML tags.
Specifies the Font Family used for text.
You can specify any valid HTML Font Family. Default is to use the browser default variable width font.
Specifying FontFace will cause the text to be enclosed in <FONT FACE=yourfontface[ Possible other font attributes]></FONT> HTML tags.
Specifies a specific point-size to use for text.
You can specify any valid HTML point size. Default is to use the browser default point-size.
Specifying FontPointsize will cause the text to be enclosed in <FONT POINT-SIZE=yourpointsize[ Possible other font attributes]></FONT> HTML tags.
Specifies a font size to use for text.
You can specify any valid HTML font size. Default is not to set the font size.
Specifying a FontSize will cause the text to be enclosed in <FONT SIZE=yoursize[ Possible other font attributes]></FONT> HTML tags.
Specifies one or more font styles to use for text.
Font Styles must be specified with one or more of the words (capitalization MUST match: Blink, Bold, Italic, Small, Strike, Sub, Super, and Underline. If several style words are specified, they must be delimited by ' ' (space). Default is not to set any font style.
Specifying TitleFontStyle will cause the Title text to be enclosed in the HTML tags producing the specified font style(s). The font style HTML tags will be surrounded by possible <FONT></FONT> tags caused by other specifications.
Specifies the maximum number of columns used when displaying the dataseries legends.
You can specify any positive integer greater than or equal to 0. Default is to use one line (row) per legend (which resembles setting LegendColumns to 1).
If both LegendColumns and LegendRows are specifyed then the LegendRows specification will be ignored!
Example: In order to use half as many lines (or nearly half if you display an uneven number of dataseries) for the list of legends you can set LegendColumns to "2":
Specifies the maximum number of rows used when displaying the dataseries legends.
You can specify any positive integer greater than or equal to 0. Default is to use one line (row) per legend (which resembles setting LegendColumns to 1).
If both LegendColumns and LegendRows are specifyed then the LegendRows specification will be ignored!
Example: In order to keep all the legends on a single line you can set LegendRows to "1" - AND LEAVE LegendColumns UNDEFINED:
With ObjectTitles... attributes you may set the background, font, and text alignment used for displaying the list of legends.
The legend text used for each dataseries are taken from the appropriate column of the "r1" input row. These text strings CAN'T be changed by using the Legend attribute!
All Legend Title attributes are using corresponding browser/document defaults as default.
Default is to show the list of legends at the bottom of the graph area. Trying to specify another LegendLocation is not allowed.
Setting Height and Width for the legend area has not yet been implemented.
Actually the list of legends is a table of it's own - as default each different legend is shown on a separate line. Long legend texts will not wrap around, as you might normally expect, but is more likely to cause the width of the graph to be pulled out of proportions. Use shorter legend texts to prevent this from happening. You can use the LegendColumns or LegendRows attributes to modify the number of columns and rows in the table with legends.
Example of specifying horizontal alignment, background color, text color, and font size used for the list of legends:
Text to be used in an area.
The text might even contain HTML tags etc., but the whole text will be enclosed in , as well as other character formatting tags, if the TitleFont attributes refered to below are used. The effects of this must be taken into account!
Specifies the horizontal alignment within an area.
The URL to an image (.GIF or .JPG) to use as background image for the area holding this Title/text.
NOTICE: Usage of background images has not been tested.
The background color used for the area holding this Title/text.
Allows you to control the color, font family (face), size, etc. of the font used for this Title/text.
Specifies the height of the area holding this Title/text.
What it is.
Valid values. Default value.
Consequences. Other comments.
Specifies the vertical alignment within an area.
Specifies the width of the area holding this Title/text.
Allows you to control the color, font family (face), size, etc. of the font used for the tick labels along the X-axis.
Can be used to make the X-axis vertical in stead of horizontal. (I.e. bars will be shown as horizontal bars in stead of vertical.
Must be set to "Vertical" to get horizontal bars. Default is horizontal.
Making the X-axis vertical allows for longer and more tick tabels on the X-axis.
Specifies number of x-values to skip over between each X-axis tick label.
Must be a positive integer number or zero. Default value is zero (i.e. there will be a tick label for every x-value).
If the tick labels on the X-axis tends to pull the graph out of scale, you might use the X-axis skip factor to reduce the number of tick labels. This way there will be more space available for those left.
Allows you to control the actual title text, as well as the font used, and the background and size of the area for the X-axis title.
Allows you to control the color, font family (face), size, etc. of the font used for the tick labels along the Y-axis.
The interval between each tick label on the (Y-)axis.
Any positive value may be used. The default value is calculated from the actual values to be displayed in an attempt to provide an autoscaling functionality.
The autoscaling functionality is one of the things, which I see as a great challenge. It is probably neither so clever nor sophisticated as you or I could desire, and it is probably subject to many redesigns to come.
The maximum value shown on the (Y-)axis.
Any positive value may be used. The default value is calculated from the actual values to be displayed in an attempt to provide an autoscaling functionality.
The autoscaling functionality is one of the things, which I see as a great challenge. It is probably neither so clever nor sophisticated as you or I could desire, and it is probably subject to many redesigns to come.
The minimum value shown on the (Y-)axis.
Any positive value or zero may be used. The default value is calculated from the actual values to be displayed in an attempt to provide an autoscaling functionality.
The autoscaling functionality is one of the things, which I see as a great challenge. It is probably neither so clever nor sophisticated as you or I could desire, and it is probably subject to many redesigns to come.
Allows you to control the actual title text, as well as the font used, and the background and size of the area for the Y-axis title.
| $Date: 2003-10-22 02:23:48+02 $ | $Author: christian $ | $Revision: 1.5 $ |
|---|