[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  
   4  /**
   5   * @file
   6   * This file documents the hooks invoked by the Signup module.
   7   */
   8  
   9  /**
  10   * Hook to define panes available to insert into the signup form.
  11   *
  12   * Panes should be provided by callback functions as a FormAPI array.
  13   * The callback should have the following signature:
  14   *   function my_callback(&$signup_form, &$form_state, $node, $signup, $pane_id, $signup_type = 'auth')
  15   * See signup_basic_form_form for an example.
  16   * The values submitted to the form elements defined by this form will be 
  17   * serialized and stored in the {signup_log} table as 'form_data'.
  18   *
  19   * @param $node
  20   *  (optional) The node being considered for panes.
  21   *  Most modules won't need to look at this, but you may need to only return
  22   *  panes if the node satisfies certain properties.
  23   *
  24   * @return
  25   *   An array of possible forms, keyed by a unique ID. Each value is itself an 
  26   *   array of data, with the following key-value pairs:
  27   *     - 'label': (required) The human-readable name of the form.
  28   *     - 'description': (required) Extra information about the form.
  29   *     - 'callback': (required) The name of a function.
  30   *     - 'operations': (optional) A list of links for the user to perform 
  31   *        administrative tasks on this pane, either global or per-node settings.
  32   *        The format is an unkeyed array of link arrays (suitable for passing
  33   *        to theme_links).
  34   *        You may use %nid as a token in your link's href property to
  35   *        insert the node id of the current signup node. 
  36   *        The following optional keys are also available:
  37   *        - destination: if set to TRUE, the return destination will be appended
  38   *          to the link as a query string with drupal_get_destination, allowing
  39   *          the user to return to this page directly. Do not use if your link
  40   *          sends the user to a complex series of forms or pages.
  41   *        - not_defaults: if set to TRUE, this link will not be shown when 
  42   *          default signup settings are being edited at admin/settings/signup.
  43   *          Use this when your settings link would be meaningless in this 
  44   *          context because it is dependent on the current node.
  45   *
  46   * @see signup_basic_form_form.
  47   */
  48  function hook_signup_pane_info($node = NULL) {
  49    return array(
  50      'basic' => array(
  51        'label' => 'Basic form',
  52        'description' => 'Collects name and phone number.',
  53        'callback' => 'signup_basic_form_form',
  54      ),  
  55    );
  56  }
  57  
  58  /**
  59   * Hook to alter signup data before a signup is inserted or updated.
  60   *
  61   * @param $signup
  62   *   Reference to the fully-loaded signup object representing the signup.
  63   *   Modules implementing this hook may prevent a signup from going ahead by
  64   *   setting $signup->block_signup = TRUE.
  65   *   It is up to the implementing module to provide a message to the user to
  66   *   explain why their attempt to sign up has failed.
  67  * @param $form_values
  68   *   Array of form values (if any) from the signup being inserted or updated.
  69   */
  70  function hook_signup_data_alter(&$signup, $form_values) {
  71    // TODO
  72  }
  73  
  74  /**
  75   * Hook invoked when a signup is being canceled.
  76   *
  77   * At the time this hook is invoked the record about the signup in the
  78   * {signup_log} table still exists, but the node has already had its signup
  79   * total decremented.
  80   *
  81   * @param $node
  82   *   The fully-loaded node object that the signup is being canceled from.
  83   * @param $signup
  84   *   An object containing all the known information about the signup being
  85   *   canceled. Contains all the data from the {signup_log} row representing
  86   *   the canceled signup. See the schema definition for descriptions of each
  87   *   field and what they represent.
  88   *
  89   * @return
  90   *   Ignored.
  91   *
  92   * @see signup_cancel_signup()
  93   */
  94  function hook_signup_cancel($signup, $node) {
  95    $info = array();
  96    $info[] = t('Signup ID: @sid', array('@sid' => $signup->sid));
  97    $info[] = t('Node ID: @nid', array('@nid' => $signup->nid));
  98    $info[] = t('User ID: @uid', array('@uid' => $signup->uid));
  99    $info[] = t('Email address for anonymous signup: @anon_mail', array('@anon_mail' => $signup->anon_mail));
 100    $info[] = t('Date/time when the signup was created: @signup_time', array('@signup_time' => $signup->signup_time));
 101    $form_data = unserialize($signup->form_data);
 102    $info[] = t('Custom signup form data: %signup_form_data', array('%signup_form_data' => theme('signup_custom_data_email', $form_data)));
 103    $info[] = t('Attendance record: %attended', array('%attended' => theme('signup_attended_text', $signup->attended)));
 104    $info[] = t('Slots consumed by this signup: @count_towards_limit', array('@co
 105  unt_towards_limit' => $signup->count_towards_limit));
 106  
 107    drupal_set_message(theme('item_list', $info, t('Signup canceled for %node_title', array('%node_title' => $node->title))));
 108  }
 109  
 110  /**
 111   * Hook invoked after a signup has been inserted.
 112   *
 113   * @param $signup
 114   *   The fully-loaded signup object representing the new signup.
 115   */
 116  function hook_signup_insert($signup) {
 117    // TODO
 118  }
 119  
 120  /**
 121   * Hook invoked after a signup has been updated.
 122   *
 123   * @param $signup
 124   *   The fully-loaded signup object representing the updated signup.
 125   */
 126  function hook_signup_update($signup) {
 127    // TODO
 128  }
 129  
 130  /**
 131   * Hook invoked when a signup is being created to gather other signup data.
 132   *
 133   * This hook allows other modules to inject information into the custom signup
 134   * data for each signup.  The array is merged with the values of any custom
 135   * fields from hook_signup_pane_info(), serialized, and stored in the
 136   * {signup_log} database table.
 137   *
 138   * @param $node
 139   *   Fully-loaded node object being signed up to.
 140   * @param $account
 141   *   Full-loaded user object who is signing up.
 142   *
 143   * @return
 144   *   Keyed array of fields to include in the custom data for this signup. The
 145   *   keys for the array are used as labels when displaying the field, so they
 146   *   should be human-readable (and wrapped in t() to allow translation).
 147   *
 148   * @see signup_sign_up_user()
 149   * @see hook_signup_pane_info()
 150   */
 151  function hook_signup_sign_up($node, $account) {
 152    return array(
 153      t('Node type') => node_get_types('name', $node->type),
 154      t('User created') => format_date($account->created),
 155    );
 156  }
 157  
 158  
 159  /**
 160   * Hook invoked whenever a node is reopened for signups.
 161   *
 162   * A node with signups closed could be reopened in two main cases: 1) someone
 163   * cancels a signup and the signup limit is no longer reached; 2) a signup
 164   * administrator manually re-opens signups.
 165   *
 166   * @param $node
 167   *   Fully-loaded node object that is now open for signups.
 168   *
 169   * @return
 170   *   Ignored.
 171   *
 172   * @see signup_open_signup()
 173   */
 174  function hook_signup_open($node) {
 175    drupal_set_message(t('Duplicate message: signups are now open on %title.', array('%title' => $node->title)));
 176  }
 177  
 178  
 179  /**
 180   * Hook invoked whenever a node is closed for signups.
 181   *
 182   * Signups are closed in 3 main cases: 1) it is a time-based node and the
 183   * close-in-advance time has been reached (auto-close via cron); 2) the node
 184   * has a signup limit and the limit is reached; 3) a signup administrator
 185   * manually closes signups.
 186   *
 187   * @param $node
 188   *   Fully-loaded node object that is now closed for signups.
 189   *
 190   * @return
 191   *   Ignored.
 192   *
 193   * @see signup_close_signup()
 194   */
 195  function hook_signup_close($node) {
 196    drupal_set_message(t('Duplicate message: signups are now closed on %title.', array('%title' => $node->title)));
 197  }
 198  
 199  
 200  /**
 201   * Hook invoked to see if signup information should be printed for a node.
 202   *
 203   * This hook is invoked whenever someone is viewing a signup-enabled node and
 204   * allows modules to suppress any signup-related output.  If any module's
 205   * implementation of this hook returns TRUE, no signup information will be
 206   * printed for that node.
 207   *
 208   * @param $node
 209   *   The fully-loaded node object being viewed.
 210   *
 211   * @return
 212   *   TRUE if you want to prevent signup information from being printed, FALSE
 213   *   or NULL if the information should be printed.
 214   *
 215   * @see _signup_needs_output()
 216   * @see _signup_menu_access()
 217   * @see signup_nodeapi()
 218   */
 219  function hook_signup_suppress($node) {
 220    if ($node->nid % 2) {
 221      drupal_set_message(t('Signup information suppressed for odd node ID %nid.', array('%nid' => $node->nid)));
 222      return TRUE;
 223    }
 224  }
 225  
 226  /**
 227   * Hook invoked to control access to signup menu items.
 228   *
 229   * This hook is invoked to check access for signup menu items, in particular,
 230   * the signup-related tabs on signup-enabled nodes. If no value is returned
 231   * (NULL), the hook is ignored and the usual access logic is enforced via the
 232   * Signup module. If multiple modules return a value, the logical OR is used,
 233   * so if anyone returns TRUE, access is granted. If everyone returns FALSE,
 234   * access is denied (even if the Signup module would normally grant access).
 235   *
 236   * @param $node
 237   *   The fully-loaded node object where the menu items would be attached.
 238   * @param $menu_type
 239   *   String specifying what kind of menu item to test access for. Can be:
 240   *   'signup': the signup form
 241   *   'list': the signup attendee listing
 242   *   'admin': the signup administration tab
 243   *   'add': the signup administration tab to add other users (requires
 244   *          that signups are currently open on the given node).
 245   *   'broadcast': for the broadcast tab
 246   *
 247   * @return
 248   *   TRUE if you want to allow access to the requested menu item, FALSE if you
 249   *   want to deny access (although if another hook implementation returns
 250   *   TRUE, that will take precedence), or NULL if you don't care and want to
 251   *   let Signup module itself decide access based on its own logic.
 252   *
 253   * @see _signup_menu_access()
 254   */
 255  function hook_signup_menu_access($node, $menu_type) {
 256    // For example, you might want to test that the current user is the
 257    // administrator of the organic group that a signup-enabled node belongs to,
 258    // in which case, you'd return TRUE here to give that user full signup
 259    // powers over events in their group.
 260  }
 261  
 262  /**
 263   * Implementation of hook_signup_form_data_display_alter().
 264   *
 265   * Allow modules to alter signup form data prior to displaying signup records
 266   * in, for example, a node's list of signups at node/N/signups/admin.
 267   *
 268   * This allows modules that implement signup panes for format or even inject 
 269   * their own data.
 270   *
 271   * @param $form_data
 272   *  The user's signup data to alter.
 273   * @param $nid
 274   *  The node id for the signup-enabled node.
 275   * @param $sid
 276   *  The signup record id.
 277   * @param $uid
 278   *  The user id whose signup this is; 0 if this is an anonymous signup.
 279   * @param $type
 280   *  The type of output being prepared. Possible values are:
 281   *    - 'list': The hardcoded admin lists of signups, eg at node/X/signups/admin
 282   *    - 'view': The form data field in Views.
 283   *    - 'mail': Email output. This is likely the only one that needs special 
 284   *      handling; in this case, modules should be more generous about supplying
 285   *      data since there's no other place to see it.
 286   */
 287  function hook_signup_form_data_display_alter(&$form_data, $nid, $sid, $uid, $type = 'list') {
 288    foreach ($form_data as $pane_id => $pane_data) {
 289      // If this is one of your panes, do stuff to it.
 290    }
 291  }