signup_pane_example.module in Signup 6.2

signup_pane_example.module A very simple example signup pane module.

File

modules/signup_pane_example/signup_pane_example.module

<?php

/**
 * @file signup_pane_example.module
 * A very simple example signup pane module.
 */

/**
 * Implementation of hook_signup_pane_info().
 *
 * Defines panes available to signup forms.
 * 
 * @param $node
 *  (optional) The node being considered for panes.
 *  Most modules won't need to look at this, but you may need to only return
 *  panes if the node satisfies certain properties.
 *
 * @return
 *  An associative array of data about signup form panes. 
 *  The key is the pane ID. The value is itself an associative array of the
 *  following form:
 *    - label: A label for the admin UI.
 *    - description: A longer description for the admin UI.
 *    - callback: A callback function to generate the form.
 *  The callback function should have the following signature:
 *   function my_callback(&$signup_form, &$form_state, $node, $signup, $pane_id, $signup_type = 'auth')
 *  where the parameters are:
 *  - $signup_form: Incoming form array, for information only.
 *  - $form_state: Incoming array from the form builder function.
 *  - $node: The fully loaded node object.
 *  - $signup: The fully loaded signup object; or NULL if this is a new signup.
 *  - $pane_id: The id of the pane currently being invoked. This allows a module
 *    to use one callback for several panes.
 *  - $signup_type: The type of signup, which may influence what form is returned:
 *    - 'auth' -- regular authenticated user signup form
 *    - 'anon' -- anonymous user signup form (main form includes required email field).
 *    - 'admin' -- admin form to signup another user (main form includes user selector).
 */
function signup_pane_example_signup_pane_info($node = NULL) {
  return array(
    'example' => array(
      'label' => t('Favourite colour'),
      'description' => t('Should probably be blue.'),
      'callback' => 'signup_pane_example_form',
    ),
  );
}

/**
 * Signup form pane callback.
 *
 * If you are handling your own data storage for this form, you should load any
 * existing data here and load it into the '#default_value' attribute for each
 * element of the returned array.
 *
 * @param &$signup_form
 *   The form array for the whole signup. You should not alter this, but it
 *   contains useful data depending on circumstances.
 * @param &$form_state
 *   Likewise.
 * @param $node
 *   The fully loaded node object.
 * @param $signup
 *   If this is an existing signup, the fully loaded node object. If this is a 
 *   new signup, this is just NULL.
 * @param $pane_id
 *   The pane ID being invoked. This allows a module to implement multiple panes
 *   with one callback.
 * @param $signup_type
 *   Determines what kind of signup to generate a form for. Possible values:
 *    'auth' -- regular authenticated user signup form
 *    'anon' -- anonymous user signup form (includes required email field).
 *    'admin' -- admin form to signup another user (includes user selector).
 * @return
 *   A form API array for insertion into the signup form.
 */
function signup_pane_example_form(&$signup_form, &$form_state, $node, $signup, $pane_id, $signup_type = 'auth') {
  $form['favorite_color'] = array(
    '#type' => 'textfield',
    '#title' => t('Favourite colour'),
    '#size' => 40,
    '#maxlength' => 64,
    '#required' => TRUE,
  );
  return $form;
}

/**
 * Form validation function for our signup pane.
 *
 * This function should be of the form PANECALLBACK_validate.
 */
function signup_pane_example_form_validate($element, &$form_state) {

  /*
  // Example validation code:
  if ($form_state['values']['signup_form_data']['example']['favorite_color'] != 'blue') {
    form_set_error('signup_form_data][example][favorite_color', t('Favourite colour must be blue.'));
  }
  */
}

/**
 * Implementation of hook_signup_data_alter().
 *
 * If we want to handle our own data storage rather than let signup module do it,
 * we can intercept a signup here before it is saved, extract our data (and
 * unset it in the incoming array), and save it to our own database tables.
 *
 * The advantage of doing this is that we can use it in Views as a field in its
 * own right, which allows sorting and filtering.
 *
 * Be aware that at this point the signup may not be assigned an sid if it is
 * a new submission. You may use signup_pane_example_signup_insert() to save
 * data after the signup has been stored in the database.
 */
function signup_pane_example_signup_data_alter(&$signup, $form_values) {

  /*
  $our_value = $signup->form_data['favorite_color'];
  // Now save our value ourselves.
  // This gets us an ID: $our_id.

  // Unset our key so it is not saved in the signup data.
  unset($signup->form_data['favorite_color']);

  // However, we have no signup sid here.
  // In order to set a connection to our own data, we put in our own data's ID
  // here, so we can retrieve it in hook_signup_insert().
  $our_id = 'coconuts';
  $signup->form_data[$pane_id] = array(
    'signup_pane_example_id' => $our_id,
  );
  */
}

/**
 * Implementation of hook_signup_insert().
 *
 * Carries on from signup_pane_example_signup_data_alter(). The signup is now
 * saved to the database and is assigned an sid.
 */
function signup_pane_example_signup_insert($signup) {

  /*
  // Retrieve the id for our own data from where we put it in the form data
  // in hook_signup_data_alter().
  $our_id = $signup->form_data[$pane_id]['signup_pane_example_id'];

  // We should now revisit our own data to save the connection between signup sid
  // and our own record for this signup.
  // Save a connection between $signup->sid and $our_id.
  */
}

/**
 * Implementation of hook_signup_form_data_display_alter().
 *
 * Alter signup form data prior to displaying signup records in, for example,
 * a node's list of signups.
 *
 * Alternatively, if we are storing data ourselves, we may wish to load it 
 * and insert it into the form_data array.
 *
 * @param $form_data
 *  The user's signup data to alter.
 * @param $nid
 *  The node id for the signup-enabled node.
 * @param $sid
 *  The signup record id. WARNING: NOT the submission sid!
 * @param $uid
 *  The user id whose signup this is; 0 if this is an anonymous signup.
 * @param $type
 *  The type of output being prepared. Possible values are:
 *    - 'list': The hardcoded admin lists of signups, eg at node/X/signups/admin
 *    - 'view': The form data field in Views.
 *    - 'mail': Email output. This is probably the only one that needs special 
 *      handling; in this case, modules should be more generous about supplying
 *      data since there's no other place to see it.
 */
function signup_pane_example_signup_form_data_display_alter(&$form_data, $nid, $sid, $uid, $type = 'list') {
  if (isset($form_data['example'])) {

    // Change our data array key from the form element key to something nicely readable.
    $form_data['example']['Favourite colour'] = $form_data['example']['favorite_color'];
    unset($form_data['example']['favorite_color']);
  }
}

/**
 * Implementation of hook_signup_cancel().
 *
 * A signup is being cancelled. 
 * If we are storing our own data for this signup, we should delete it here.
 */

//function signup_pane_example_signup_cancel($signup, $node) { }

/**
 * Implementation of hook_nodeapi().
 *
 * A whole signup-enabled node is being deleted.
 * If we are storing our own data, we should delete all of it that relates to 
 * this node.
 */

//function signup_pane_example_nodeapi(&$node, $op, $a3 = NULL, $a4 = NULL) {

//  if ($op == 'delete') {}

//}

Functions

Name	Description
signup_pane_example_form	Signup form pane callback.
signup_pane_example_form_validate	Form validation function for our signup pane.
signup_pane_example_signup_data_alter	Implementation of hook_signup_data_alter().
signup_pane_example_signup_form_data_display_alter	Implementation of hook_signup_form_data_display_alter().
signup_pane_example_signup_insert	Implementation of hook_signup_insert().
signup_pane_example_signup_pane_info	Implementation of hook_signup_pane_info().