Graphing Package

This package relies on a few gifs being present in /graphics/graphing-package/. It also relies on the presense of ad_proc and its helper procs in utilities.tcl. Make sure you always have the latest version of utilities.tcl every time you upgrade the ACS! The graphing Tcl procedures are in /tcl/ad-graphing.tcl.

If you want to do fancier charts like x-y-scatter graphs or pie charts, you should probably buy/find/write a cgi program that generates gifs on the fly (a popular free example is Gnuplot, distributed from http://www.cs.dartmouth.edu/gnuplot_info.html). In my experience, trying to do these the plain html way is very slow and limited.

The bar chart procedure, gr_sideways_bar_chart returns an HTML fragment. It has just one mandatory argument, although there are a number of optional arguments to beautify or improve your graphs. Because there are so many optional arguments, the optional arguments are specified using flags (keyword arguments), like Unix commands, instead of positionally like most tcl procedures.

To run this command:

gr_sideways_bar_chart subcategory_category_and_value_list

To use optional arguments, for instance legend and left_heading:

gr_sideways_bar_chart -legend legend -left_heading left_heading subcategory_category_and_value_list

1. subcategory_category_and_value_list
   This is the only mandatory argument.

   To create a graph like this:

   Dogs
   Samoyed    xxxxxxxxxxx 45%
   Black Lab  xxxx 20%
   Terrier    xxxxxxxxxxxxxxxxxxxx 66%
   Cats
   Calico     xxxxxxxx 39%
   Persian    xx 10%
   

   supply subcategory_category_and_value_list as a Tcl list of lists:

   [list [list "Samoyed" "Dogs" "45"] \
         [list "Black Lab" "Dogs" "20"] \
         [list "Terrier" "Dogs" "66"] \
         [list "Calico" "Cats" "39"] \
         [list "Persian" "Cats" "10"]]
   

   Dogs and Cats are the categories, Samoyed, Black Lab, Terrier, Calico, and Persian are subcategories, and all the numbers are values. You can have multiple values per subcategory, in which case you should supply the values as a list:

   [list [list "Samoyed" "Dog" [list "45" "65" "34"]] ...]

   There can be an optional fourth argument, which specifies a URL to link around the value displayed (if values are being displayed). If provided, this overrides the setting of default_drilldown_url below.

2. legend
legend is a list of what the values refer to if there's more than one value per subcategory.

   So, if you have created a graph with three values per subcategory:

   Dogs
   Samoyed   xxxxxxxxxxx 45%
             ----------------------- 90%
             ++++++++++++++++++ 70%
   Black Lab xxxx 20%
             ------ 30%
             ++++++++++++ 60%
   

   then create a legend like

   [list "March" "April" "May (projected)"]

3. bar_color_list
   There is a default list of colors with which the values will be displayed if there is more than one value per subcategory, but if those colors don't meet your design needs, go ahead and supply your own color list.

4. display_values_p
   By default, the values (like 60%) aren't displayed after the bars, but if you want them to be, set this to "t".

5. display_scale_p
   By default, there's a scale displayed at the top of the chart that goes from 0% to 100%, but if you don't want that scale there, set display_scale_p to "f". It doesn't make sense to have the scale if the values that are being charted are not percentages.

6. default_drilldown_url
   If supplied, should be a URL to which the numeric value (if being displayed) will be linked. This variable will undergo variable expansion, so $category, $subcategory, and $value may be referenced.

7. non_percent_values_p
   Set this to "t" if the numbers you're charting are not percentages. Then this procedure will, instead of creating bars that are a fixed number times the value, display the values relative to each other (it will, in essence, pretend that the highest value within a category is 100%, and then display the other values in that category relative to each other).

8. min_left_column_width
   If you are going to stack charts, set the min_left_column_width to be the same for each of them so that they will line up. Otherwise, the left column, which contains the categories and subcategories, probably won't be the same for successive charts.

9. bar_height
   By default, the height of each bar is 15 pixels.

10. subcategory_spacing
    By default, the spacing between each subcategory is 7 pixels.

11. compare_non_percents_across_categories
    This is only relevant if you are graphing values that are not percentages. Usually (as explained above for non_percent_values_p), the bars are drawn so that they are relative only to other bars in the same category. This makes sense if one category has values like 900, 854, 942, and another totally unrelated category has values like 2.5, 3, 3.27. You wouldn't want the bars in the second category to be drawn relative to the ones in the first category because they would be very small and, besides, they're not even related. But, if the numbers ARE related across categories, then set compare_non_percents_across_categories to "t".

12. left_heading
    Stuff (text/pictures/whatever) that goes above the items on the left of the chart (i.e. above the categories and subcategories).

13. right_heading
    Stuff that goes above the items on the right of the chart (i.e. above the values).

14. replace_null_subcategory_with_none_p
    Set this to "t" to have "[none]" be displayed as the subcategory if the subcategory is the empty string.