modules/signup/signup.api.php

<?php
// $Id: signup.api.php,v 1.4 2009/09/19 00:31:56 dww Exp $


/**
 * @file
 * This file documents the hooks invoked by the Signup module.
 */

/**
 * Hook to alter signup data before a signup is inserted or updated.
 *
 * @param $signup
 *   Reference to the fully-loaded signup object representing the signup.
 * @param $form_values
 *   Array of form values (if any) from the signup being inserted or updated.
 */
function hook_signup_data_alter(&$signup, $form_values) {
  // TODO
}

/**
 * Hook invoked when a signup is being canceled.
 *
 * At the time this hook is invoked the record about the signup in the
 * {signup_log} table still exists, but the node has already had its signup
 * total decremented.
 *
 * @param $node
 *   The fully-loaded node object that the signup is being canceled from.
 * @param $signup
 *   An object containing all the known information about the signup being
 *   canceled. Contains all the data from the {signup_log} row representing
 *   the canceled signup. See the schema definition for descriptions of each
 *   field and what they represent.
 *
 * @return
 *   Ignored.
 *
 * @see signup_cancel_signup()
 */
function hook_signup_cancel($signup, $node) {
  $info = array();
  $info[] = t('Signup ID: @sid', array('@sid' => $signup->sid));
  $info[] = t('Node ID: @nid', array('@nid' => $signup->nid));
  $info[] = t('User ID: @uid', array('@uid' => $signup->uid));
  $info[] = t('Email address for anonymous signup: @anon_mail', array('@anon_mail' => $signup->anon_mail));
  $info[] = t('Date/time when the signup was created: @signup_time', array('@signup_time' => $signup->signup_time));
  $form_data = unserialize($signup->form_data);
  $info[] = t('Custom signup form data: %signup_form_data', array('%signup_form_data' => theme('signup_custom_data_email', $form_data)));
  $info[] = t('Attendance record: %attended', array('%attended' => theme('signup_attended_text', $signup->attended)));
  $info[] = t('Slots consumed by this signup: @count_towards_limit', array('@co
unt_towards_limit' => $signup->count_towards_limit));

  drupal_set_message(theme('item_list', $info, t('Signup canceled for %node_title', array('%node_title' => $node->title))));
}

/**
 * Hook invoked after a signup has been inserted.
 *
 * @param $signup
 *   The fully-loaded signup object representing the new signup.
 */
function hook_signup_insert($signup) {
  // TODO
}

/**
 * Hook invoked after a signup has been updated.
 *
 * @param $signup
 *   The fully-loaded signup object representing the updated signup.
 */
function hook_signup_update($signup) {
  // TODO
}

/**
 * Hook invoked when a signup is being created to gather other signup data.
 *
 * This hook allows other modules to inject information into the custom signup
 * data for each signup.  The array is merged with the values of any custom
 * fields from theme_signup_user_form(), serialized, and stored in the
 * {signup_log} database table.
 *
 * @param $node
 *   Fully-loaded node object being signed up to.
 * @param $account
 *   Full-loaded user object who is signing up.
 *
 * @return
 *   Keyed array of fields to include in the custom data for this signup. The
 *   keys for the array are used as labels when displaying the field, so they
 *   should be human-readable (and wrapped in t() to allow translation).
 *
 * @see signup_sign_up_user()
 * @see theme_signup_user_form()
 */
function hook_signup_sign_up($node, $account) {
  return array(
    t('Node type') => node_get_types('name', $node->type),
    t('User created') => format_date($account->created),
  );
}


/**
 * Hook invoked whenever a node is reopened for signups.
 *
 * A node with signups closed could be reopened in two main cases: 1) someone
 * cancels a signup and the signup limit is no longer reached; 2) a signup
 * administrator manually re-opens signups.
 *
 * @param $node
 *   Fully-loaded node object that is now open for signups.
 *
 * @return
 *   Ignored.
 *
 * @see signup_open_signup()
 */
function hook_signup_open($node) {
  drupal_set_message(t('Duplicate message: signups are now open on %title.', array('%title' => $node->title)));
}


/**
 * Hook invoked whenever a node is closed for signups.
 *
 * Signups are closed in 3 main cases: 1) it is a time-based node and the
 * close-in-advance time has been reached (auto-close via cron); 2) the node
 * has a signup limit and the limit is reached; 3) a signup administrator
 * manually closes signups.
 *
 * @param $node
 *   Fully-loaded node object that is now closed for signups.
 *
 * @return
 *   Ignored.
 *
 * @see signup_close_signup()
 */
function hook_signup_close($node) {
  drupal_set_message(t('Duplicate message: signups are now closed on %title.', array('%title' => $node->title)));
}


/**
 * Hook invoked to see if signup information should be printed for a node.
 *
 * This hook is invoked whenever someone is viewing a signup-enabled node and
 * allows modules to suppress any signup-related output.  If any module's
 * implementation of this hook returns TRUE, no signup information will be
 * printed for that node.
 *
 * @param $node
 *   The fully-loaded node object being viewed.
 *
 * @return
 *   TRUE if you want to prevent signup information from being printed, FALSE
 *   or NULL if the information should be printed.
 *
 * @see _signup_needs_output()
 * @see _signup_menu_access()
 * @see signup_nodeapi()
 */
function hook_signup_suppress($node) {
  if ($node->nid % 2) {
    drupal_set_message(t('Signup information suppressed for odd node ID %nid.', array('%nid' => $node->nid)));
    return TRUE;
  }
}

/**
 * Hook invoked to control access to signup menu items.
 *
 * This hook is invoked to check access for signup menu items, in particular,
 * the signup-related tabs on signup-enabled nodes. If no value is returned
 * (NULL), the hook is ignored and the usual access logic is enforced via the
 * Signup module. If multiple modules return a value, the logical OR is used,
 * so if anyone returns TRUE, access is granted. If everyone returns FALSE,
 * access is denied (even if the Signup module would normally grant access).
 *
 * @param $node
 *   The fully-loaded node object where the menu items would be attached.
 * @param $menu_type
 *   String specifying what kind of menu item to test access for. Can be:
 *   'signup': the signup form
 *   'list': the signup attendee listing
 *   'admin': the signup administration tab
 *   'add': the signup administration tab to add other users (requires
 *          that signups are currently open on the given node).
 *   'broadcast': for the broadcast tab
 *
 * @return
 *   TRUE if you want to allow access to the requested menu item, FALSE if you
 *   want to deny access (although if another hook implementation returns
 *   TRUE, that will take precedence), or NULL if you don't care and want to
 *   let Signup module itself decide access based on its own logic.
 *
 * @see _signup_menu_access()
 */
function hook_signup_menu_access($node, $menu_type) {
  // For example, you might want to test that the current user is the
  // administrator of the organic group that a signup-enabled node belongs to,
  // in which case, you'd return TRUE here to give that user full signup
  // powers over events in their group.
}

1	<?php
2	// $Id: signup.api.php,v 1.4 2009/09/19 00:31:56 dww Exp $
3
4
5	/**
6	* @file
7	* This file documents the hooks invoked by the Signup module.
8	*/
9
10	/**
11	* Hook to alter signup data before a signup is inserted or updated.
12	*
13	* @param $signup
14	* Reference to the fully-loaded signup object representing the signup.
15	* @param $form_values
16	* Array of form values (if any) from the signup being inserted or updated.
17	*/
18	function hook_signup_data_alter(&$signup, $form_values) {
19	// TODO
20	}
21
22	/**
23	* Hook invoked when a signup is being canceled.
24	*
25	* At the time this hook is invoked the record about the signup in the
26	* {signup_log} table still exists, but the node has already had its signup
27	* total decremented.
28	*
29	* @param $node
30	* The fully-loaded node object that the signup is being canceled from.
31	* @param $signup
32	* An object containing all the known information about the signup being
33	* canceled. Contains all the data from the {signup_log} row representing
34	* the canceled signup. See the schema definition for descriptions of each
35	* field and what they represent.
36	*
37	* @return
38	* Ignored.
39	*
40	* @see signup_cancel_signup()
41	*/
42	function hook_signup_cancel($signup, $node) {
43	$info = array();
44	$info[] = t('Signup ID: @sid', array('@sid' => $signup->sid));
45	$info[] = t('Node ID: @nid', array('@nid' => $signup->nid));
46	$info[] = t('User ID: @uid', array('@uid' => $signup->uid));
47	$info[] = t('Email address for anonymous signup: @anon_mail', array('@anon_mail' => $signup->anon_mail));
48	$info[] = t('Date/time when the signup was created: @signup_time', array('@signup_time' => $signup->signup_time));
49	$form_data = unserialize($signup->form_data);
50	$info[] = t('Custom signup form data: %signup_form_data', array('%signup_form_data' => theme('signup_custom_data_email', $form_data)));
51	$info[] = t('Attendance record: %attended', array('%attended' => theme('signup_attended_text', $signup->attended)));
52	$info[] = t('Slots consumed by this signup: @count_towards_limit', array('@co
53	unt_towards_limit' => $signup->count_towards_limit));
54
55	drupal_set_message(theme('item_list', $info, t('Signup canceled for %node_title', array('%node_title' => $node->title))));
56	}
57
58	/**
59	* Hook invoked after a signup has been inserted.
60	*
61	* @param $signup
62	* The fully-loaded signup object representing the new signup.
63	*/
64	function hook_signup_insert($signup) {
65	// TODO
66	}
67
68	/**
69	* Hook invoked after a signup has been updated.
70	*
71	* @param $signup
72	* The fully-loaded signup object representing the updated signup.
73	*/
74	function hook_signup_update($signup) {
75	// TODO
76	}
77
78	/**
79	* Hook invoked when a signup is being created to gather other signup data.
80	*
81	* This hook allows other modules to inject information into the custom signup
82	* data for each signup. The array is merged with the values of any custom
83	* fields from theme_signup_user_form(), serialized, and stored in the
84	* {signup_log} database table.
85	*
86	* @param $node
87	* Fully-loaded node object being signed up to.
88	* @param $account
89	* Full-loaded user object who is signing up.
90	*
91	* @return
92	* Keyed array of fields to include in the custom data for this signup. The
93	* keys for the array are used as labels when displaying the field, so they
94	* should be human-readable (and wrapped in t() to allow translation).
95	*
96	* @see signup_sign_up_user()
97	* @see theme_signup_user_form()
98	*/
99	function hook_signup_sign_up($node, $account) {
100	return array(
101	t('Node type') => node_get_types('name', $node->type),
102	t('User created') => format_date($account->created),
103	);
104	}
105
106
107	/**
108	* Hook invoked whenever a node is reopened for signups.
109	*
110	* A node with signups closed could be reopened in two main cases: 1) someone
111	* cancels a signup and the signup limit is no longer reached; 2) a signup
112	* administrator manually re-opens signups.
113	*
114	* @param $node
115	* Fully-loaded node object that is now open for signups.
116	*
117	* @return
118	* Ignored.
119	*
120	* @see signup_open_signup()
121	*/
122	function hook_signup_open($node) {
123	drupal_set_message(t('Duplicate message: signups are now open on %title.', array('%title' => $node->title)));
124	}
125
126
127	/**
128	* Hook invoked whenever a node is closed for signups.
129	*
130	* Signups are closed in 3 main cases: 1) it is a time-based node and the
131	* close-in-advance time has been reached (auto-close via cron); 2) the node
132	* has a signup limit and the limit is reached; 3) a signup administrator
133	* manually closes signups.
134	*
135	* @param $node
136	* Fully-loaded node object that is now closed for signups.
137	*
138	* @return
139	* Ignored.
140	*
141	* @see signup_close_signup()
142	*/
143	function hook_signup_close($node) {
144	drupal_set_message(t('Duplicate message: signups are now closed on %title.', array('%title' => $node->title)));
145	}
146
147
148	/**
149	* Hook invoked to see if signup information should be printed for a node.
150	*
151	* This hook is invoked whenever someone is viewing a signup-enabled node and
152	* allows modules to suppress any signup-related output. If any module's
153	* implementation of this hook returns TRUE, no signup information will be
154	* printed for that node.
155	*
156	* @param $node
157	* The fully-loaded node object being viewed.
158	*
159	* @return
160	* TRUE if you want to prevent signup information from being printed, FALSE
161	* or NULL if the information should be printed.
162	*
163	* @see _signup_needs_output()
164	* @see _signup_menu_access()
165	* @see signup_nodeapi()
166	*/
167	function hook_signup_suppress($node) {
168	if ($node->nid % 2) {
169	drupal_set_message(t('Signup information suppressed for odd node ID %nid.', array('%nid' => $node->nid)));
170	return TRUE;
171	}
172	}
173
174	/**
175	* Hook invoked to control access to signup menu items.
176	*
177	* This hook is invoked to check access for signup menu items, in particular,
178	* the signup-related tabs on signup-enabled nodes. If no value is returned
179	* (NULL), the hook is ignored and the usual access logic is enforced via the
180	* Signup module. If multiple modules return a value, the logical OR is used,
181	* so if anyone returns TRUE, access is granted. If everyone returns FALSE,
182	* access is denied (even if the Signup module would normally grant access).
183	*
184	* @param $node
185	* The fully-loaded node object where the menu items would be attached.
186	* @param $menu_type
187	* String specifying what kind of menu item to test access for. Can be:
188	* 'signup': the signup form
189	* 'list': the signup attendee listing
190	* 'admin': the signup administration tab
191	* 'add': the signup administration tab to add other users (requires
192	* that signups are currently open on the given node).
193	* 'broadcast': for the broadcast tab
194	*
195	* @return
196	* TRUE if you want to allow access to the requested menu item, FALSE if you
197	* want to deny access (although if another hook implementation returns
198	* TRUE, that will take precedence), or NULL if you don't care and want to
199	* let Signup module itself decide access based on its own logic.
200	*
201	* @see _signup_menu_access()
202	*/
203	function hook_signup_menu_access($node, $menu_type) {
204	// For example, you might want to test that the current user is the
205	// administrator of the organic group that a signup-enabled node belongs to,
206	// in which case, you'd return TRUE here to give that user full signup
207	// powers over events in their group.
208	}
209