modules/uts/uts.hooks.data.php

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

/**
 * Define data collection the module provides. This provides the name and
 * description that will be displayed to both the user and is used to
 * determine what module can be used to collect data.
 *
 * @return array Data collection plug-in information.
 *
 *   The array should use the module name as a key and contain the following
 *   keys-value pairs (all required):
 *
 *   - "name": Name used to reference the data collection plug-in.
 *   - "description": Short description of the module that can be easily
 *     understood by both the test creator and the participant.
 *   - "software_require": Client side software requirements.
 *   - "javascript": Boolean javascript required.
 */
function hook_uts_data_collection() {
  return array(
    'uts_plugin' => array(
      'name' => t('Plug-in name'),
      'description' => t('Plug-in description.'),
      'software_require' => FALSE,
      'javascript' => FALSE
    )
  );
}

/**
 * Define the client requirements and their status. This behaves similarly to
 * hook_requirements(). If the requirements are not met and the data collection
 * plug-in is not required then it will not be enabled for collection. If the
 * plug-in is required and the requirements are not met then it will not allow
 * the participant to continue until the requirements are satisfied.
 *
 * @return array Data collection plug-in information.
 *
 *   The array should use the module name as a key and contain the following
 *   keys-value pairs (all required):
 *
 *   - "status": The requirements status, one of:
 *       - 'ok': Requirement satisfied.
 *       - 'warning': Requirement satisfied, but there is a warning.
 *       - 'error': Requirement not satisfied.
 *   - "name": Name used to reference the data collection plug-in.
 *   - "description": Short description of the module that can be easily
 *     understood by both the test creator and the participant.
 */
function hook_uts_client_requirements() {
  return array(
    'uts_plugin' => array(
      'status' => 'ok',
      'name' => t('Client requirement'),
      'description' => t('All requirements met, data collection enabled.')
    )
  );
}

/**
 * Retrieve the data collected by the plug-in for the specified parameters.
 * Just the first parameter or all the parameters must be specified.
 *
 * @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 within the specified paramters.
 *
 *   The array should use the module name as a key and contain rows of data
 *   with each element being an array key. There is not stringent requirement
 *   since data can be in many different formats. The data will be requested by
 *   analysis plug-ins that should know what to do with the returned data.
 */
function hook_uts_data_get($study_nid, $session_id = NULL, $start_timestamp = NULL, $stop_timestamp = NULL) {
  if ($session_id && $start_timestamp && $stop_timestamp) {
    $result = db_query("SELECT p.session_id, p.timestamp, p.element1, p.element2
                        FROM {uts_plugin} p, {uts_session} s
                        WHERE p.session_id = s.session_id
                        AND s.study_nid = %d
                        AND p.timestamp >= %d
                        AND p.timestamp <= %d
                        AND p.session_id = '%s'
                        ORDER BY timestamp ASC", $study_nid, $start_timestamp, $stop_timestamp, $session_id);
  }
  else {
    $result = db_query("SELECT p.session_id, p.timestamp, p.element1, p.element2
                        FROM {uts_plugin} p, {uts_session} s
                        WHERE p.session_id = s.session_id
                        AND s.study_nid = %d
                        ORDER BY timestamp ASC", $study_nid);
  }
  $data = array();
  while ($record = db_fetch_array($result)) {
    $data[] = $record;
  }
  return array('uts_plugin' => $data);
}

/**
 * Delete data stored by data collection plug-in within the specified
 * parameters. The plug-ins are responsible for removing all data of any kind
 * be it files or database records.
 *
 * @param interger $study_nid Study NID.
 * @param string $session_id Session ID.
 */
function hook_uts_data_delete($study_nid, $session_id = NULL) {
  if ($session_id) {
    db_query("DELETE FROM {uts_plugin}
              WHERE session_id = '%s'", $session_id);
  }
  else {
    $sessions = uts_session_load_all($study_nid);
    if (count($sessions) > 0) {
      $placeholders = implode("','", array_fill(0, count($sessions), '%s'));
      db_query("DELETE FROM {uts_plugin}
                WHERE session_id IN ('$placeholders')", $sessions);
    }
  }
}

/**
 * Perform startup tasks upon the beginning of a study task. This hook is
 * called after the participant presses the "Start" button and begins the
 * a new task.
 *
 * This is not intended for code that takes a long time to execute as it will
 * hold up the participant.
 *
 * @param int $timestamp Standardized timestamp of the task completion time.
 */
function hook_uts_data_started_task($timestamp) {

}

/**
 * Perform cleanup or closure tasks upon the completion of a study task. This
 * hook is called after the participant presses the "Done" button or runs out of
 * time and is automatically forwarded to the next task.
 *
 * This is not intended for code that takes a long time to execute as it will
 * hold up the participant.
 *
 * @param int $timestamp Standardized timestamp of the task completion time.
 */
function hook_uts_data_completed_task($timestamp) {

}

/**
 * Perform cleanup or closure tasks upon the completion of a study. This hook
 * is called when the participant has completed all the tasks in the study.
 *
 * @param int $timestamp Standardized timestamp of the study completion time.
 */
function hook_uts_data_completed_study($timestamp) {

}
1	<?php
2	// $Id: uts.hooks.data.php,v 1.1 2008/08/16 22:04:38 boombatower Exp $
3	/**
4	* @file
5	* Provide data collection hook documentation for Usability Testing Suite.
6	*
7	* Copyright 2008 by Jimmy Berry ("boombatower", http://drupal.org/user/214218)
8	*/
9
10	/**
11	* Define data collection the module provides. This provides the name and
12	* description that will be displayed to both the user and is used to
13	* determine what module can be used to collect data.
14	*
15	* @return array Data collection plug-in information.
16	*
17	* The array should use the module name as a key and contain the following
18	* keys-value pairs (all required):
19	*
20	* - "name": Name used to reference the data collection plug-in.
21	* - "description": Short description of the module that can be easily
22	* understood by both the test creator and the participant.
23	* - "software_require": Client side software requirements.
24	* - "javascript": Boolean javascript required.
25	*/
26	function hook_uts_data_collection() {
27	return array(
28	'uts_plugin' => array(
29	'name' => t('Plug-in name'),
30	'description' => t('Plug-in description.'),
31	'software_require' => FALSE,
32	'javascript' => FALSE
33	)
34	);
35	}
36
37	/**
38	* Define the client requirements and their status. This behaves similarly to
39	* hook_requirements(). If the requirements are not met and the data collection
40	* plug-in is not required then it will not be enabled for collection. If the
41	* plug-in is required and the requirements are not met then it will not allow
42	* the participant to continue until the requirements are satisfied.
43	*
44	* @return array Data collection plug-in information.
45	*
46	* The array should use the module name as a key and contain the following
47	* keys-value pairs (all required):
48	*
49	* - "status": The requirements status, one of:
50	* - 'ok': Requirement satisfied.
51	* - 'warning': Requirement satisfied, but there is a warning.
52	* - 'error': Requirement not satisfied.
53	* - "name": Name used to reference the data collection plug-in.
54	* - "description": Short description of the module that can be easily
55	* understood by both the test creator and the participant.
56	*/
57	function hook_uts_client_requirements() {
58	return array(
59	'uts_plugin' => array(
60	'status' => 'ok',
61	'name' => t('Client requirement'),
62	'description' => t('All requirements met, data collection enabled.')
63	)
64	);
65	}
66
67	/**
68	* Retrieve the data collected by the plug-in for the specified parameters.
69	* Just the first parameter or all the parameters must be specified.
70	*
71	* @param interger $study_nid Study NID.
72	* @param string $session_id Session ID.
73	* @param interger $start_timestamp Start timestamp.
74	* @param integer $stop_timestamp Stop timestamp.
75	* @return array Data within the specified paramters.
76	*
77	* The array should use the module name as a key and contain rows of data
78	* with each element being an array key. There is not stringent requirement
79	* since data can be in many different formats. The data will be requested by
80	* analysis plug-ins that should know what to do with the returned data.
81	*/
82	function hook_uts_data_get($study_nid, $session_id = NULL, $start_timestamp = NULL, $stop_timestamp = NULL) {
83	if ($session_id && $start_timestamp && $stop_timestamp) {
84	$result = db_query("SELECT p.session_id, p.timestamp, p.element1, p.element2
85	FROM {uts_plugin} p, {uts_session} s
86	WHERE p.session_id = s.session_id
87	AND s.study_nid = %d
88	AND p.timestamp >= %d
89	AND p.timestamp <= %d
90	AND p.session_id = '%s'
91	ORDER BY timestamp ASC", $study_nid, $start_timestamp, $stop_timestamp, $session_id);
92	}
93	else {
94	$result = db_query("SELECT p.session_id, p.timestamp, p.element1, p.element2
95	FROM {uts_plugin} p, {uts_session} s
96	WHERE p.session_id = s.session_id
97	AND s.study_nid = %d
98	ORDER BY timestamp ASC", $study_nid);
99	}
100	$data = array();
101	while ($record = db_fetch_array($result)) {
102	$data[] = $record;
103	}
104	return array('uts_plugin' => $data);
105	}
106
107	/**
108	* Delete data stored by data collection plug-in within the specified
109	* parameters. The plug-ins are responsible for removing all data of any kind
110	* be it files or database records.
111	*
112	* @param interger $study_nid Study NID.
113	* @param string $session_id Session ID.
114	*/
115	function hook_uts_data_delete($study_nid, $session_id = NULL) {
116	if ($session_id) {
117	db_query("DELETE FROM {uts_plugin}
118	WHERE session_id = '%s'", $session_id);
119	}
120	else {
121	$sessions = uts_session_load_all($study_nid);
122	if (count($sessions) > 0) {
123	$placeholders = implode("','", array_fill(0, count($sessions), '%s'));
124	db_query("DELETE FROM {uts_plugin}
125	WHERE session_id IN ('$placeholders')", $sessions);
126	}
127	}
128	}
129
130	/**
131	* Perform startup tasks upon the beginning of a study task. This hook is
132	* called after the participant presses the "Start" button and begins the
133	* a new task.
134	*
135	* This is not intended for code that takes a long time to execute as it will
136	* hold up the participant.
137	*
138	* @param int $timestamp Standardized timestamp of the task completion time.
139	*/
140	function hook_uts_data_started_task($timestamp) {
141
142	}
143
144	/**
145	* Perform cleanup or closure tasks upon the completion of a study task. This
146	* hook is called after the participant presses the "Done" button or runs out of
147	* time and is automatically forwarded to the next task.
148	*
149	* This is not intended for code that takes a long time to execute as it will
150	* hold up the participant.
151	*
152	* @param int $timestamp Standardized timestamp of the task completion time.
153	*/
154	function hook_uts_data_completed_task($timestamp) {
155
156	}
157
158	/**
159	* Perform cleanup or closure tasks upon the completion of a study. This hook
160	* is called when the participant has completed all the tasks in the study.
161	*
162	* @param int $timestamp Standardized timestamp of the study completion time.
163	*/
164	function hook_uts_data_completed_study($timestamp) {
165
166	}