modules/graphstat/README.txt

*****************************************************************************
                            G R A P H S T A T
*****************************************************************************
Name: graphstat module
Author: Thilo Wawrzik <drupal at profix898 dot de>
Original Author (Drupal 4.7): Dries Knapen
Drupal: 6.0
*****************************************************************************
DESCRIPTION:

Graphstat uses data from the statistics, user, node, and comment
modules to generate statistical graphs.

It uses PHPLOT library (http://www.phplot.com/) to render the
graphs, which is available under GPL License and PHP License.
PHPLOT requires the GD library available with PHP.

*****************************************************************************
INSTALLATION:

1. Place whole graphstat folder into your Drupal modules/ directory.

2. Enable the graphstat module by navigating to
     Administer > Site Building > Modules (admin/build/modules)
     
3. View the graphs at
    Administer > Reports > Graphs (admin/reports/graphs)

*****************************************************************************
API:

Graphstat provides an easy way to add additional graphs and graph
groups/pages. It introduces the new hook_graphstat() which takes a
simple data structure specifying all graph parameters.

The following function is a commented sample implementation of
hook_graphstat():

function mymodule_graphstat() {
  $graphs = array();
  $graphs['sample'] = array(
    // Title of the graph group/page
    'title' => t('Sample Graphs'),
    // Content added above the graphs on the page (optional)
    'pre' => t('Pre graphs comment'),
    // Content added below the graphs on the page (optional)
    'post' => t('Post graphs comment'),
    // Filter definition (optional)
    'filter' => array(
      // Array containing all possible filter options
      'options' => array('keyA' => 'optionA', ...),
      // A callback function invoked when the user changes
      // the filter settings. (see below for details)
      'callback' => 'filter_callback'
    ),
    // The first sample graph
    'graph_sample1' => array(
      // Plot style of this graph (optional)
      // possible values:  bars, lines, linepoints (default), area,
      //                   points, pie, thinbarline, squared
      'type' => 'bars',
      // Title of this graph
      'title' => t('Graph Daily 1'),
      // Label on the X-Axis
      'xlabel' => t('X Label'),
      // Label on the Y-Axis
      'ylabel' => t('Y Label'),
      // Legend for pie/bars plots (optional)
      'legend' => array(t('dataA'), t('dataB')),
      // Array containing the data points
      // possible formats:  1. array('x1' => 'y1', ...)
      //                    2. array(array('x1', 'y1'), ...)
      //                    3. array(array('x1', 'y1', 'y2'), ...)
      'data' => array('x1' => 'y1', 'x2' => 'y2'),
      // Description for this graph (optional)
      'description' => t('description for the graph')
    ),
    // The second sample graph
    'graph_sample2' => array(
      ...
    )
  );
  
  return $graphs;
}

In case the structure returned in hook_graphstat() defines a filter
the filter callback function is invoked everytime the user chooses
a different filter option from the filter dropdown.
Two parameters are passed into the callback function:
 1. The $graphs structure (by reference)
 2. The selected filter option (e.g. 'keyA', ...)
The callback function modifies the $graphs structure based on the
selected $filter option. For example it replaces the 'data' field
with a data array matching the filter option. But it can also alter
the labels, plot style, etc. of the graphs.

function filter_callback(&$graphs, $filter) {
  $graph['graph_sample1'] = array( ... );
  $graph['graph_sample2']['data'] = array( ... );
}

You may also take a look at graphstat_statistics.inc for some
sample functions, e.g. graphstat_statistics_nodes().
Function graphstat_statistics_daily() additionally shows the use of
filters, where graphstat_statistics_daily_filter() is the filter
callback.

*****************************************************************************
Have fun with graphstat, Thilo.
1	*****************************************************************************
2	G R A P H S T A T
3	*****************************************************************************
4	Name: graphstat module
5	Author: Thilo Wawrzik <drupal at profix898 dot de>
6	Original Author (Drupal 4.7): Dries Knapen
7	Drupal: 6.0
8	*****************************************************************************
9	DESCRIPTION:
10
11	Graphstat uses data from the statistics, user, node, and comment
12	modules to generate statistical graphs.
13
14	It uses PHPLOT library (http://www.phplot.com/) to render the
15	graphs, which is available under GPL License and PHP License.
16	PHPLOT requires the GD library available with PHP.
17
18	*****************************************************************************
19	INSTALLATION:
20
21	1. Place whole graphstat folder into your Drupal modules/ directory.
22
23	2. Enable the graphstat module by navigating to
24	Administer > Site Building > Modules (admin/build/modules)
25
26	3. View the graphs at
27	Administer > Reports > Graphs (admin/reports/graphs)
28
29	*****************************************************************************
30	API:
31
32	Graphstat provides an easy way to add additional graphs and graph
33	groups/pages. It introduces the new hook_graphstat() which takes a
34	simple data structure specifying all graph parameters.
35
36	The following function is a commented sample implementation of
37	hook_graphstat():
38
39	function mymodule_graphstat() {
40	$graphs = array();
41	$graphs['sample'] = array(
42	// Title of the graph group/page
43	'title' => t('Sample Graphs'),
44	// Content added above the graphs on the page (optional)
45	'pre' => t('Pre graphs comment'),
46	// Content added below the graphs on the page (optional)
47	'post' => t('Post graphs comment'),
48	// Filter definition (optional)
49	'filter' => array(
50	// Array containing all possible filter options
51	'options' => array('keyA' => 'optionA', ...),
52	// A callback function invoked when the user changes
53	// the filter settings. (see below for details)
54	'callback' => 'filter_callback'
55	),
56	// The first sample graph
57	'graph_sample1' => array(
58	// Plot style of this graph (optional)
59	// possible values: bars, lines, linepoints (default), area,
60	// points, pie, thinbarline, squared
61	'type' => 'bars',
62	// Title of this graph
63	'title' => t('Graph Daily 1'),
64	// Label on the X-Axis
65	'xlabel' => t('X Label'),
66	// Label on the Y-Axis
67	'ylabel' => t('Y Label'),
68	// Legend for pie/bars plots (optional)
69	'legend' => array(t('dataA'), t('dataB')),
70	// Array containing the data points
71	// possible formats: 1. array('x1' => 'y1', ...)
72	// 2. array(array('x1', 'y1'), ...)
73	// 3. array(array('x1', 'y1', 'y2'), ...)
74	'data' => array('x1' => 'y1', 'x2' => 'y2'),
75	// Description for this graph (optional)
76	'description' => t('description for the graph')
77	),
78	// The second sample graph
79	'graph_sample2' => array(
80	...
81	)
82	);
83
84	return $graphs;
85	}
86
87	In case the structure returned in hook_graphstat() defines a filter
88	the filter callback function is invoked everytime the user chooses
89	a different filter option from the filter dropdown.
90	Two parameters are passed into the callback function:
91	1. The $graphs structure (by reference)
92	2. The selected filter option (e.g. 'keyA', ...)
93	The callback function modifies the $graphs structure based on the
94	selected $filter option. For example it replaces the 'data' field
95	with a data array matching the filter option. But it can also alter
96	the labels, plot style, etc. of the graphs.
97
98	function filter_callback(&$graphs, $filter) {
99	$graph['graph_sample1'] = array( ... );
100	$graph['graph_sample2']['data'] = array( ... );
101	}
102
103	You may also take a look at graphstat_statistics.inc for some
104	sample functions, e.g. graphstat_statistics_nodes().
105	Function graphstat_statistics_daily() additionally shows the use of
106	filters, where graphstat_statistics_daily_filter() is the filter
107	callback.
108
109	*****************************************************************************
110	Have fun with graphstat, Thilo.