modules/reports/reports.module

<?php
// $Id: reports.module,v 1.5 2007/03/30 02:03:05 hlslaughter Exp $

/**
 * @file
 * Site useage reports.
 *
 * The idea here is to allow for creation of arbitrary reports by generating
 * a small amount of information for the report, including the SQL required.
 * I do not want all of the restrictions and bugs that come with trying to
 * abstract the SQL out of the DB layer.
 *
 * My top priority is automating as much of the process as possible. The cost
 * of that will probably be features. I want to be uber simple, extremely
 * easy to use and customize (for developers). There is a lot of information
 * in the drupal db, but not an easy way to present it to users.
 *
 * TODO:
 * - report caching: many reports will quickly become cumbersome/expensive on
 *   sites with lots of data. First thought is to create a report query cksum
 *   as cid and tmp cache results.
 * - data cooking: for 'advanced' reports, like user sessions, it won't
 *   be practical to calculate information for each request.
 * - date widget: a 'global' and sticky report date widget for filtering to
 *   a date range. Boolean to turn on/off for given report.
 * - filters:
 * - permissions: My initial assumption is that only admins will have access
 *   to these reports, but I could be wrong. Maybe I should allow for
 *   access control on a per-report basis?
 * - report categorization and grouping:
 * - some sort of testing of reports before they are run? are they valid?
 */

define(DEFAULT_HELP_TEXT, 'The Reports module is still in development and should not be used on production sites');


/**
 * Implementation of hook_help().
 */
function reports_help($section) {
  switch ($section) {
    case 'admin/help#reports':
      return t(DEFAULT_HELP_TEXT);
      break;
    case 'admin/reports':
      return t(DEFAULT_HELP_TEXT);
      break;
    case 'admin/modules#description':
      return t(DEFAULT_HELP_TEXT);
      break;
    case 'admin/settings/reports':
      return t(DEFAULT_HELP_TEXT);
      break;
  }
}

/**
 * Implementation of hook_perm().
 */
function reports_perm() {
  return array('administer reports', 'view reports');
}

/**
 * Implementation of hook_menu().
 */
function reports_menu($may_cache) {
  $items = array();

  if ($may_cache) {
    $items[] = array(
      'path'               => 'reports',
      'title'              => t('View Reports'),
      'description'        => t('Site useage reports.'),
      'access'             => user_access('view reports'),
      'callback'           => 'reports_view',
      'weight'             => 0,
      'type'               => MENU_NORMAL_ITEM
    );
    $items[] = array(
      'path'               => 'admin/settings/reports',
      'title'              => t('Reports'),
      'description'        => t('Configure reports.'),
      'callback'           => 'drupal_get_form',
      'callback arguments' => array('reports_admin_settings'),
      'weight'             => 0,
      'access'             => user_access('administer reports'),
      'type'               => MENU_NORMAL_ITEM
    );

    // Generate menu items for individual reports
    // TODO: list should actually include some properties we can use here
    $reports_list = reports_index('conf');
    foreach ( $reports_list as $id => $report ) {
// debug
//drupal_set_message("got report: <pre>" . print_r($report, TRUE) . "</pre>");

      $items[] = array(
        'path'               => 'reports/' . $id,
        'title'              => $report['#title'],
        'description'        => t($report['#description']), // TODO: does this t() work?
        'weight'             => $report['#weight'],
        'callback'           => 'reports_view',
        'callback arguments' => array($id),
        // TODO: really wondering if i should allow for optional access control
        // on a per report basis...
        'access'             => user_access('view reports'),
        'type'               => MENU_NORMAL_ITEM
      );
    }

  } else {
    //drupal_add_css(drupal_get_path('module', 'reports') . '/reports.css');
  }
  return $items;
}

/**
 * Implementation of hook_cron().
 *
 * TODO: will need this if we want to cook data
 */
function reports_cron() {
  return TRUE;
}

/**
 * Menu callback. Display reports.
 */
function reports_view($report = NULL) {

  $output = '';

  if ( empty($report) ) {
    $output .= 'Reports homepage, maybe a fancy dhtml panel displaying available
      reports?';
  } else {
    // TODO:
    $output .= reports_generate_graph($report);
    $output .= reports_generate_report($report);
  }
  return $output;
}

/**
 * Generate report data table
 *
 * @param (string)$report
 *  The name of the report to be generated
 *
 * @return (type)
 *   description
 */
function reports_generate_report($report) {
  $output = '';
  $r = reports_index('conf', $report);

//debug
//drupal_set_message('got $r: <pre>' . print_r($r, TRUE) . '</pre>');
//return;

  // set defaults for optional report properties
  if ( !isset($r['#results_per_page']) ) {
    $r['#results_per_page'] = variable_get('reports_default_results_per_page', 50);
  }

  $num_results = db_num_rows(db_query($r['#sql']));
  $count_query = "SELECT $num_results";

  $result = pager_query($r['#sql'] . tablesort_sql($r['#table_header']), $r['#results_per_page'], 0, $count_query, NULL);

  $rows = array();
  while ($record = db_fetch_array($result)) {
    $rows[] = $record;
  }

  $output .= '<div class="report_description">' . $r['#description'] . '</div>';
  drupal_set_title(check_plain($r['#title']));
  $output .= theme('table', $r['#table_header'], $rows) .  theme('pager', NULL, $r['#results_per_page']);
  return $output;
}

/**
 * Description
 *
 * @param $array
 *
 *
 * @return (type)
 *   description
 */
function reports_generate_graph($report) {
  return;
}

/**
 * Return config info for reports
 *
 * @param (string)$request
 *   Type of data being requested
 *   - conf: all configuration info
 *   - list: report keys (names)
 *
 * @param (string)$report
 *   (optional) The name of the report
 *
 * @return (type)
 *   description
 */
function reports_index($request, $report = NULL) {
  // not sure where/how we'll ultimately store reports config data, but want
  // indexing functionality encapsulated.
  require_once(drupal_get_path('module', 'reports') .'/reports_definitions.inc');
  global $reports_config;

// debug
//drupal_set_message("in index got: $report and got request: $request");

  switch ($request) {
    case 'list':
      return array_keys($reports_config);
      break;
    case 'conf':
      if ( isset($report) ) {
        return($reports_config[$report]);
      } else {
        return $reports_config;
      }
      break;
    default:
      watchdog('reports', "Undefined request (<em>$request<em>) to reports_index()", WATCHDOG_ERROR);
      break;
  }
}

function reports_admin_settings() {

  // General
  $form['general'] = array(
    '#type'          => 'fieldset',
    '#title'         => t('General settings'),
    '#collapsible'   => TRUE,
    '#description'   => t('TODO: description')
  );
  $form['general']['reports_default_results_per_page'] = array(
    '#type'          => 'textfield',
    '#size'          => 5,
    '#title'         => t('Default results per page'),
    '#description'   => t('Number of results to be displayed on a reports page if
      not specified by the report itself'),
    '#default_value' => variable_get('reports_default_results_per_page', 50),
  );

  /*
  // Sessions
  $form['sessions'] = array(
    '#type'          => 'fieldset',
    '#title'         => t('User sessions'),
    '#collapsible'   => TRUE,
    '#description'   => t('Define parameters for user session'),
  );
  $form['sessions']['reports_sessions_timeout'] = array(
    '#type'          => 'textfield',
    '#size'          => 5,
    '#title'         => t('Session timeout'),
    '#description'   => t('Length of time (in seconds) of time after which a sessions is considered ended'),
    '#default_value' => variable_get('reports_sessions_timeout', 900),
  );

  // Filters
  $form['filters'] = array(
    '#type'          => 'fieldset',
    '#title'         => t('Filters'),
    '#collapsible'   => TRUE,
    '#description'   => t('Global exclude filters allow for the excluding of users, referrers
      and other types of info from the reports.')
  );
  $form['filters']['reports_hide_self_referral'] = array(
    '#type'          => 'checkbox',
    '#title'         => t('Hide self referrals'),
    '#description'   => t('Exclude <b>@site</b> from referrer reports.',
      array('@site'  => variable_get('site_name', 'EMPTY'))
    ),
    '#default_value' => variable_get('reports_hide_self_referral', 0),
  );

  // Graphs
  $form['graphs'] = array(
    '#type'         => 'fieldset',
    '#title'        => t('Graph settings'),
    '#collapsible'  => TRUE,
    '#description'  => t('TODO: description')
  );
  */
  return system_settings_form($form);
}
1	<?php
2	// $Id: reports.module,v 1.5 2007/03/30 02:03:05 hlslaughter Exp $
3
4	/**
5	* @file
6	* Site useage reports.
7	*
8	* The idea here is to allow for creation of arbitrary reports by generating
9	* a small amount of information for the report, including the SQL required.
10	* I do not want all of the restrictions and bugs that come with trying to
11	* abstract the SQL out of the DB layer.
12	*
13	* My top priority is automating as much of the process as possible. The cost
14	* of that will probably be features. I want to be uber simple, extremely
15	* easy to use and customize (for developers). There is a lot of information
16	* in the drupal db, but not an easy way to present it to users.
17	*
18	* TODO:
19	* - report caching: many reports will quickly become cumbersome/expensive on
20	* sites with lots of data. First thought is to create a report query cksum
21	* as cid and tmp cache results.
22	* - data cooking: for 'advanced' reports, like user sessions, it won't
23	* be practical to calculate information for each request.
24	* - date widget: a 'global' and sticky report date widget for filtering to
25	* a date range. Boolean to turn on/off for given report.
26	* - filters:
27	* - permissions: My initial assumption is that only admins will have access
28	* to these reports, but I could be wrong. Maybe I should allow for
29	* access control on a per-report basis?
30	* - report categorization and grouping:
31	* - some sort of testing of reports before they are run? are they valid?
32	*/
33
34	define(DEFAULT_HELP_TEXT, 'The Reports module is still in development and should not be used on production sites');
35
36
37	/**
38	* Implementation of hook_help().
39	*/
40	function reports_help($section) {
41	switch ($section) {
42	case 'admin/help#reports':
43	return t(DEFAULT_HELP_TEXT);
44	break;
45	case 'admin/reports':
46	return t(DEFAULT_HELP_TEXT);
47	break;
48	case 'admin/modules#description':
49	return t(DEFAULT_HELP_TEXT);
50	break;
51	case 'admin/settings/reports':
52	return t(DEFAULT_HELP_TEXT);
53	break;
54	}
55	}
56
57	/**
58	* Implementation of hook_perm().
59	*/
60	function reports_perm() {
61	return array('administer reports', 'view reports');
62	}
63
64	/**
65	* Implementation of hook_menu().
66	*/
67	function reports_menu($may_cache) {
68	$items = array();
69
70	if ($may_cache) {
71	$items[] = array(
72	'path' => 'reports',
73	'title' => t('View Reports'),
74	'description' => t('Site useage reports.'),
75	'access' => user_access('view reports'),
76	'callback' => 'reports_view',
77	'weight' => 0,
78	'type' => MENU_NORMAL_ITEM
79	);
80	$items[] = array(
81	'path' => 'admin/settings/reports',
82	'title' => t('Reports'),
83	'description' => t('Configure reports.'),
84	'callback' => 'drupal_get_form',
85	'callback arguments' => array('reports_admin_settings'),
86	'weight' => 0,
87	'access' => user_access('administer reports'),
88	'type' => MENU_NORMAL_ITEM
89	);
90
91	// Generate menu items for individual reports
92	// TODO: list should actually include some properties we can use here
93	$reports_list = reports_index('conf');
94	foreach ( $reports_list as $id => $report ) {
95	// debug
96	//drupal_set_message("got report: <pre>" . print_r($report, TRUE) . "</pre>");
97
98	$items[] = array(
99	'path' => 'reports/' . $id,
100	'title' => $report['#title'],
101	'description' => t($report['#description']), // TODO: does this t() work?
102	'weight' => $report['#weight'],
103	'callback' => 'reports_view',
104	'callback arguments' => array($id),
105	// TODO: really wondering if i should allow for optional access control
106	// on a per report basis...
107	'access' => user_access('view reports'),
108	'type' => MENU_NORMAL_ITEM
109	);
110	}
111
112	} else {
113	//drupal_add_css(drupal_get_path('module', 'reports') . '/reports.css');
114	}
115	return $items;
116	}
117
118	/**
119	* Implementation of hook_cron().
120	*
121	* TODO: will need this if we want to cook data
122	*/
123	function reports_cron() {
124	return TRUE;
125	}
126
127	/**
128	* Menu callback. Display reports.
129	*/
130	function reports_view($report = NULL) {
131
132	$output = '';
133
134	if ( empty($report) ) {
135	$output .= 'Reports homepage, maybe a fancy dhtml panel displaying available
136	reports?';
137	} else {
138	// TODO:
139	$output .= reports_generate_graph($report);
140	$output .= reports_generate_report($report);
141	}
142	return $output;
143	}
144
145	/**
146	* Generate report data table
147	*
148	* @param (string)$report
149	* The name of the report to be generated
150	*
151	* @return (type)
152	* description
153	*/
154	function reports_generate_report($report) {
155	$output = '';
156	$r = reports_index('conf', $report);
157
158	//debug
159	//drupal_set_message('got $r: <pre>' . print_r($r, TRUE) . '</pre>');
160	//return;
161
162	// set defaults for optional report properties
163	if ( !isset($r['#results_per_page']) ) {
164	$r['#results_per_page'] = variable_get('reports_default_results_per_page', 50);
165	}
166
167	$num_results = db_num_rows(db_query($r['#sql']));
168	$count_query = "SELECT $num_results";
169
170	$result = pager_query($r['#sql'] . tablesort_sql($r['#table_header']), $r['#results_per_page'], 0, $count_query, NULL);
171
172	$rows = array();
173	while ($record = db_fetch_array($result)) {
174	$rows[] = $record;
175	}
176
177	$output .= '<div class="report_description">' . $r['#description'] . '</div>';
178	drupal_set_title(check_plain($r['#title']));
179	$output .= theme('table', $r['#table_header'], $rows) . theme('pager', NULL, $r['#results_per_page']);
180	return $output;
181	}
182
183	/**
184	* Description
185	*
186	* @param $array
187	*
188	*
189	* @return (type)
190	* description
191	*/
192	function reports_generate_graph($report) {
193	return;
194	}
195
196	/**
197	* Return config info for reports
198	*
199	* @param (string)$request
200	* Type of data being requested
201	* - conf: all configuration info
202	* - list: report keys (names)
203	*
204	* @param (string)$report
205	* (optional) The name of the report
206	*
207	* @return (type)
208	* description
209	*/
210	function reports_index($request, $report = NULL) {
211	// not sure where/how we'll ultimately store reports config data, but want
212	// indexing functionality encapsulated.
213	require_once(drupal_get_path('module', 'reports') .'/reports_definitions.inc');
214	global $reports_config;
215
216	// debug
217	//drupal_set_message("in index got: $report and got request: $request");
218
219	switch ($request) {
220	case 'list':
221	return array_keys($reports_config);
222	break;
223	case 'conf':
224	if ( isset($report) ) {
225	return($reports_config[$report]);
226	} else {
227	return $reports_config;
228	}
229	break;
230	default:
231	watchdog('reports', "Undefined request (<em>$request<em>) to reports_index()", WATCHDOG_ERROR);
232	break;
233	}
234	}
235
236	function reports_admin_settings() {
237
238	// General
239	$form['general'] = array(
240	'#type' => 'fieldset',
241	'#title' => t('General settings'),
242	'#collapsible' => TRUE,
243	'#description' => t('TODO: description')
244	);
245	$form['general']['reports_default_results_per_page'] = array(
246	'#type' => 'textfield',
247	'#size' => 5,
248	'#title' => t('Default results per page'),
249	'#description' => t('Number of results to be displayed on a reports page if
250	not specified by the report itself'),
251	'#default_value' => variable_get('reports_default_results_per_page', 50),
252	);
253
254	/*
255	// Sessions
256	$form['sessions'] = array(
257	'#type' => 'fieldset',
258	'#title' => t('User sessions'),
259	'#collapsible' => TRUE,
260	'#description' => t('Define parameters for user session'),
261	);
262	$form['sessions']['reports_sessions_timeout'] = array(
263	'#type' => 'textfield',
264	'#size' => 5,
265	'#title' => t('Session timeout'),
266	'#description' => t('Length of time (in seconds) of time after which a sessions is considered ended'),
267	'#default_value' => variable_get('reports_sessions_timeout', 900),
268	);
269
270	// Filters
271	$form['filters'] = array(
272	'#type' => 'fieldset',
273	'#title' => t('Filters'),
274	'#collapsible' => TRUE,
275	'#description' => t('Global exclude filters allow for the excluding of users, referrers
276	and other types of info from the reports.')
277	);
278	$form['filters']['reports_hide_self_referral'] = array(
279	'#type' => 'checkbox',
280	'#title' => t('Hide self referrals'),
281	'#description' => t('Exclude <b>@site</b> from referrer reports.',
282	array('@site' => variable_get('site_name', 'EMPTY'))
283	),
284	'#default_value' => variable_get('reports_hide_self_referral', 0),
285	);
286
287	// Graphs
288	$form['graphs'] = array(
289	'#type' => 'fieldset',
290	'#title' => t('Graph settings'),
291	'#collapsible' => TRUE,
292	'#description' => t('TODO: description')
293	);
294	*/
295	return system_settings_form($form);
296	}