modules/uts/uts.data.inc

<?php
// $Id: uts.data.inc,v 1.10 2008/08/16 22:04:38 boombatower Exp $
/**
 * @file
 * Provide Usability Testing Suite data functions and hook implementations.
 *
 * Copyright 2008 by Jimmy Berry ("boombatower", http://drupal.org/user/214218)
 */

/**
 * Get a list of all the data collection plug-ins available.
 *
 * @return array List of data colleciton plug-ins.
 * @see hook_uts_data_collection()
 */
function uts_data_collection_list() {
  return module_invoke_all('uts_data_collection');
}

/**
 * Get a list of client requirements.
 *
 * @return array List of client requirements.
 * @see hook_uts_client_requirements()
 */
function uts_data_client_requirements() {
  return module_invoke_all('uts_client_requirements');
}

/**
 * Get data collected from all enabled data plug-ins. Specified just the first
 * parameter or all the parameters.
 *
 * @param interger $study_nid Study NID.
 * @param string $session_id Session ID.
 * @param interger $start_timestamp Start timestamp.
 * @param integer $stop_timestamp Stop timestamp.
 * @return array Data from plug-ins.
 * @see hook_uts_data_get()
 */
function uts_data_get($study_nid, $session_id = NULL, $start_timestamp = NULL, $stop_timestamp = NULL) {
  return module_invoke_all('uts_data_get', $study_nid, $session_id, $start_timestamp, $stop_timestamp);
}

/**
 * Delete data stored by data collection plug-ins.
 *
 * @param interger $study_nid Study NID.
 * @param string $session_id Session ID.
 * @see hook_uts_data_delete()
 */
function uts_data_delete($study_nid, $session_id = NULL) {
  module_invoke_all('uts_data_delete', $study_nid, $session_id);
}

/**
 * Get the start and stop timestamps for a given session. The function can
 * be called in the following three manors.
 *
 * ($sessiond_id)
 * ($sessiond_id, $start_and_stop_task_id)
 * ($sessiond_id, $start_task_id, $stop_task_id)
 *
 * @param string $session_id Session ID.
 * @param integer $start_task_id Start task ID (or both if no stop task specified).
 * @param integer $stop_task_id Stop task ID.
 * @param boolean $return_now Return time() if there is no stop timestamp. Only
 *   set to FALSE when calculating time spent on each task.
 *
 * @return array First element is the start time and second is the stop time.
 */
function uts_data_get_timestamps($session_id, $start_task_id = NULL, $stop_task_id = NULL, $return_now = TRUE) {
  if ($stop_task_id) {
    // All variable already set.
  }
  elseif ($start_task_id) {
    $stop_task_id = $start_task_id;
  }
  else {
    // Get first and last tasks in the study.
    $session = uts_session_load($session_id);
    $tasks = uts_tasks_load($session->study_nid);
    $first = array_shift($tasks);
    $last = ($tasks ? array_pop($tasks) : $first);

    $start_task_id = $first->nid;
    $stop_task_id = $last->nid;
  }
  $start = db_result(db_query("SELECT start_time
                               FROM {uts_session_task}
                               WHERE session_id = '%s'
                               AND task_nid = %d", $session_id, $start_task_id));
  $stop = db_result(db_query("SELECT stop_time
                              FROM {uts_session_task}
                              WHERE session_id = '%s'
                              AND task_nid = %d", $session_id, $stop_task_id));
  // Usually just want date range to query data from plugins.
  if ($return_now && $stop === FALSE) {
    $stop = time();
  }
  return array($start, $stop);
}

/**
 * Get the total time taken to complete a study.
 *
 * @param string $session_id Session ID to get total time taken.
 * @return interger Total time taken to complete study.
 */
function uts_data_get_total_time($session_id) {
  $session = uts_session_load($session_id);
  $study_nid = $session->study_nid;
  $tasks = uts_tasks_load($study_nid);

  // Cycle through each task and add up the time spent.
  $total = 0;
  foreach ($tasks as $task) {
    list($start, $stop) = uts_data_get_timestamps($session_id, $task->nid);
    $total += ($stop - $start);
  }
  return $total;
}

/**
 * Get a list of data analysis plug-ins.
 *
 * @return array List of data analysis plug-ins.
 * @see hook_uts_data_analysis()
 */
function uts_data_analysis_list() {
  return module_invoke_all('uts_data_analysis');
}

/**
 * Get a generated analysis from plug-ins.
 *
 * @param string $module Data collection module from which data will be retrieved.
 * @param string $mode The analysis mode.
 * @param interger $study_nid Study NID.
 * @param string $session_id Session ID.
 * @param interger $start_timestamp Start timestamp.
 * @param integer $stop_timestamp Stop timestamp.
 * @return array Generated analysis.
 * @see hook_uts_data_display()
 */
function uts_data_analysis_display($module, $mode, $study_nid, $session_id = NULL, $start_timestamp = NULL, $stop_timestamp = NULL) {
  return module_invoke_all('uts_data_display', $module, $mode, $study_nid, $session_id, $start_timestamp, $stop_timestamp);
}

/**
 * Get a generated analysis exportation from plug-ins.
 *
 * @param string $module Data collection module from which data will be retrieved.
 * @param string $mode The analysis mode.
 * @param interger $study_nid Study NID.
 * @param string $session_id Session ID.
 * @param interger $start_timestamp Start timestamp.
 * @param integer $stop_timestamp Stop timestamp.
 * @return array Generated analysis.
 * @see hook_uts_data_analysis_export().
 */
function uts_data_analysis_export($module, $mode, $study_nid, $session_id = NULL, $start_timestamp = NULL, $stop_timestamp = NULL) {
  return module_invoke_all('uts_data_analysis_export', $module, $mode, $study_nid, $session_id, $start_timestamp, $stop_timestamp);
}
1	<?php
2	// $Id: uts.data.inc,v 1.10 2008/08/16 22:04:38 boombatower Exp $
3	/**
4	* @file
5	* Provide Usability Testing Suite data functions and hook implementations.
6	*
7	* Copyright 2008 by Jimmy Berry ("boombatower", http://drupal.org/user/214218)
8	*/
9
10	/**
11	* Get a list of all the data collection plug-ins available.
12	*
13	* @return array List of data colleciton plug-ins.
14	* @see hook_uts_data_collection()
15	*/
16	function uts_data_collection_list() {
17	return module_invoke_all('uts_data_collection');
18	}
19
20	/**
21	* Get a list of client requirements.
22	*
23	* @return array List of client requirements.
24	* @see hook_uts_client_requirements()
25	*/
26	function uts_data_client_requirements() {
27	return module_invoke_all('uts_client_requirements');
28	}
29
30	/**
31	* Get data collected from all enabled data plug-ins. Specified just the first
32	* parameter or all the parameters.
33	*
34	* @param interger $study_nid Study NID.
35	* @param string $session_id Session ID.
36	* @param interger $start_timestamp Start timestamp.
37	* @param integer $stop_timestamp Stop timestamp.
38	* @return array Data from plug-ins.
39	* @see hook_uts_data_get()
40	*/
41	function uts_data_get($study_nid, $session_id = NULL, $start_timestamp = NULL, $stop_timestamp = NULL) {
42	return module_invoke_all('uts_data_get', $study_nid, $session_id, $start_timestamp, $stop_timestamp);
43	}
44
45	/**
46	* Delete data stored by data collection plug-ins.
47	*
48	* @param interger $study_nid Study NID.
49	* @param string $session_id Session ID.
50	* @see hook_uts_data_delete()
51	*/
52	function uts_data_delete($study_nid, $session_id = NULL) {
53	module_invoke_all('uts_data_delete', $study_nid, $session_id);
54	}
55
56	/**
57	* Get the start and stop timestamps for a given session. The function can
58	* be called in the following three manors.
59	*
60	* ($sessiond_id)
61	* ($sessiond_id, $start_and_stop_task_id)
62	* ($sessiond_id, $start_task_id, $stop_task_id)
63	*
64	* @param string $session_id Session ID.
65	* @param integer $start_task_id Start task ID (or both if no stop task specified).
66	* @param integer $stop_task_id Stop task ID.
67	* @param boolean $return_now Return time() if there is no stop timestamp. Only
68	* set to FALSE when calculating time spent on each task.
69	*
70	* @return array First element is the start time and second is the stop time.
71	*/
72	function uts_data_get_timestamps($session_id, $start_task_id = NULL, $stop_task_id = NULL, $return_now = TRUE) {
73	if ($stop_task_id) {
74	// All variable already set.
75	}
76	elseif ($start_task_id) {
77	$stop_task_id = $start_task_id;
78	}
79	else {
80	// Get first and last tasks in the study.
81	$session = uts_session_load($session_id);
82	$tasks = uts_tasks_load($session->study_nid);
83	$first = array_shift($tasks);
84	$last = ($tasks ? array_pop($tasks) : $first);
85
86	$start_task_id = $first->nid;
87	$stop_task_id = $last->nid;
88	}
89	$start = db_result(db_query("SELECT start_time
90	FROM {uts_session_task}
91	WHERE session_id = '%s'
92	AND task_nid = %d", $session_id, $start_task_id));
93	$stop = db_result(db_query("SELECT stop_time
94	FROM {uts_session_task}
95	WHERE session_id = '%s'
96	AND task_nid = %d", $session_id, $stop_task_id));
97	// Usually just want date range to query data from plugins.
98	if ($return_now && $stop === FALSE) {
99	$stop = time();
100	}
101	return array($start, $stop);
102	}
103
104	/**
105	* Get the total time taken to complete a study.
106	*
107	* @param string $session_id Session ID to get total time taken.
108	* @return interger Total time taken to complete study.
109	*/
110	function uts_data_get_total_time($session_id) {
111	$session = uts_session_load($session_id);
112	$study_nid = $session->study_nid;
113	$tasks = uts_tasks_load($study_nid);
114
115	// Cycle through each task and add up the time spent.
116	$total = 0;
117	foreach ($tasks as $task) {
118	list($start, $stop) = uts_data_get_timestamps($session_id, $task->nid);
119	$total += ($stop - $start);
120	}
121	return $total;
122	}
123
124	/**
125	* Get a list of data analysis plug-ins.
126	*
127	* @return array List of data analysis plug-ins.
128	* @see hook_uts_data_analysis()
129	*/
130	function uts_data_analysis_list() {
131	return module_invoke_all('uts_data_analysis');
132	}
133
134	/**
135	* Get a generated analysis from plug-ins.
136	*
137	* @param string $module Data collection module from which data will be retrieved.
138	* @param string $mode The analysis mode.
139	* @param interger $study_nid Study NID.
140	* @param string $session_id Session ID.
141	* @param interger $start_timestamp Start timestamp.
142	* @param integer $stop_timestamp Stop timestamp.
143	* @return array Generated analysis.
144	* @see hook_uts_data_display()
145	*/
146	function uts_data_analysis_display($module, $mode, $study_nid, $session_id = NULL, $start_timestamp = NULL, $stop_timestamp = NULL) {
147	return module_invoke_all('uts_data_display', $module, $mode, $study_nid, $session_id, $start_timestamp, $stop_timestamp);
148	}
149
150	/**
151	* Get a generated analysis exportation from plug-ins.
152	*
153	* @param string $module Data collection module from which data will be retrieved.
154	* @param string $mode The analysis mode.
155	* @param interger $study_nid Study NID.
156	* @param string $session_id Session ID.
157	* @param interger $start_timestamp Start timestamp.
158	* @param integer $stop_timestamp Stop timestamp.
159	* @return array Generated analysis.
160	* @see hook_uts_data_analysis_export().
161	*/
162	function uts_data_analysis_export($module, $mode, $study_nid, $session_id = NULL, $start_timestamp = NULL, $stop_timestamp = NULL) {
163	return module_invoke_all('uts_data_analysis_export', $module, $mode, $study_nid, $session_id, $start_timestamp, $stop_timestamp);
164	}