source: sipes/modules_contrib/token/token_actions.module @ c43ea01

<?php

/**
 * @file
 * The Token Actions module.
 *
 * The Token Actions module provides ways to use tokens inside of actions.
 * Currently it provides the ability to show users a message, send a token-ized
 * mail, or redirect a user to a tokenized URL.
 *
 * @ingroup token
 */

/**
 * Implements hook_action_info().
 */
function token_actions_action_info() {
  return array(
    'token_actions_message_action' => array(
      'type' => 'system',
      'description' => t('Display a tokenized message to the user'),
      'configurable' => TRUE,
      'hooks' => array(
        'nodeapi' => array('view', 'insert', 'update', 'delete'),
        'comment' => array('view', 'insert', 'update', 'delete'),
        'user' => array('view', 'insert', 'update', 'delete', 'login'),
        'taxonomy' => array('insert', 'update', 'delete'),
      ),
    ),
    'token_actions_send_email_action' => array(
      'description' => t('Send tokenized e-mail'),
      'type' => 'system',
      'configurable' => TRUE,
      'hooks' => array(
        'nodeapi' => array('view', 'insert', 'update', 'delete'),
        'comment' => array('view', 'insert', 'update', 'delete'),
        'user' => array('view', 'insert', 'update', 'delete', 'login'),
        'taxonomy' => array('insert', 'update', 'delete'),
      )
    ),
    'token_actions_goto_action' => array(
      'description' => t('Redirect to a tokenized URL'),
      'type' => 'system',
      'configurable' => TRUE,
      'hooks' => array(
        'nodeapi' => array('view', 'insert', 'update', 'delete'),
        'comment' => array('view', 'insert', 'update', 'delete'),
        'user' => array('view', 'insert', 'update', 'delete', 'login'),
      )
    )
  );
}

/**
 * Implements hook_mail().
 */
function token_actions_mail($key, &$message, $params) {
  $message['subject'] = $params['subject'];
  $message['body'][] = $params['body'];
}

/**
 * Action callback to send a tokenized e-mail.
 *
 * @see token_actions_send_email_action_form()
 * @see token_actions_send_email_action_submit()
 */
function token_actions_send_email_action($object, $context) {
  token_normalize_context($context);
  $params['from'] = variable_get('site_mail', ini_get('sendmail_from'));
  $recipient = token_replace_multiple($context['recipient'], $context);
  $params['subject'] = str_replace(array("\r", "\n"), '', token_replace_multiple($context['subject'], $context));
  $params['body'] = token_replace_multiple($context['message'], $context);

  if (drupal_mail('token_actions', 'action_send_email', $recipient, language_default(), $params)) {
    watchdog('action', 'Sent email to %recipient', array('%recipient' => $recipient));
  }
  else {
    watchdog('error', 'Unable to send email to %recipient', array('%recipient' => $recipient));
  }
}

/**
 * Form builder; Prepare a form for a tokenized e-mail action.
 *
 * @see token_actions_send_email_action()
 * @see token_actions_send_email_action_validate()
 * @see token_actions_send_email_action_submit()
 */
function token_actions_send_email_action_form($context) {
  // Set default values for form.
  $context += array(
    'recipient' => '',
    'subject' => '',
    'message' => '',
  );

  $form['recipient'] = array(
    '#type' => 'textfield',
    '#title' => t('Recipient'),
    '#default_value' => $context['recipient'],
    '#required' => TRUE,
    '#size' => '20',
    '#maxlength' => '254',
    '#description' => t('The email address to which the message should be sent.'),
    '#element_validate' => array('token_element_validate'),
    '#token_types' => array('all'),
  );
  $form['subject'] = array(
    '#type' => 'textfield',
    '#title' => t('Subject'),
    '#default_value' => $context['subject'],
    '#size' => '20',
    '#maxlength' => '254',
    '#description' => t('The subject of the message.'),
    '#element_validate' => array('token_element_validate'),
    '#token_types' => array('all'),
  );
  $form['message'] = array(
    '#type' => 'textarea',
    '#title' => t('Message'),
    '#default_value' => $context['message'],
    '#required' => TRUE,
    '#cols' => '80',
    '#rows' => '20',
    '#description' => t('The message that should be sent.'),
    '#element_validate' => array('token_element_validate'),
    '#token_types' => array('all'),
  );

  $form['help'] = array(
    '#type' => 'fieldset',
    '#collapsible' => TRUE,
    '#collapsed' => TRUE,
    '#title' => t('Placeholder tokens'),
    '#description' => t("The following placeholder tokens can be used in to generate the URL path. Some tokens may not be available, depending on the context in which the action is triggered."),
  );
  $form['help']['tokens'] = array(
    '#value' => theme('token_tree', 'all'),
  );

  return $form;
}

/**
 * Validate token_actions_send_email_action form submissions.
 *
 * @see token_actions_send_email_action()
 * @see token_actions_send_email_action_form()
 * @see token_actions_send_email_action_submit()
 */
function token_actions_send_email_action_validate($form, $form_state) {
  $form_values = $form_state['values'];
  if (!valid_email_address($form_values['recipient']) && strpos($form_values['recipient'], 'mail') === FALSE) {
    // We want the literal %mail placeholder to be emphasized in the error message.
    form_set_error('recipient', t('Enter a valid email address or use a token e-mail address such as %mail.', array('%mail' => '[mail]')));
  }
}

/**
 * Process token_actions_send_email_action form submissions.
 *
 * @see token_actions_send_email_action()
 * @see token_actions_send_email_action_form()
 * @see token_actions_send_email_action_validate()
 */
function token_actions_send_email_action_submit($form, $form_state) {
  return array(
    'recipient' => $form_state['values']['recipient'],
    'subject'   => $form_state['values']['subject'],
    'message'   => $form_state['values']['message'],
  );
}

/**
 * Action callback to send a message to the current user's screen.
 *
 * @see token_actions_message_action_form()
 * @see token_actions_message_action_submit()
 */
function token_actions_message_action(&$object, $context = array()) {
  token_normalize_context($context);
  $context['message'] = token_replace_multiple($context['message'], $context);
  drupal_set_message($context['message']);
}

/**
 * Form builder; Prepare a form for a tokenized message action.
 *
 * @see token_actions_message_action()
 * @see token_actions_message_action_submit()
 */
function token_actions_message_action_form($context) {
  $context += array('message' => '');

  $form['message'] = array(
    '#type' => 'textarea',
    '#title' => t('Message'),
    '#default_value' => $context['message'],
    '#required' => TRUE,
    '#rows' => '8',
    '#description' => t('The message to be displayed to the current user.'),
    '#element_validate' => array('token_element_validate'),
    '#token_types' => array('all'),
  );

  $form['help'] = array(
    '#type' => 'fieldset',
    '#collapsible' => TRUE,
    '#collapsed' => TRUE,
    '#title' => t('Placeholder tokens'),
    '#description' => t("The following placeholder tokens can be used in the custom message text. Some tokens may not be available, depending on the context in which the action is triggered."),
  );
  $form['help']['tokens'] = array(
    '#value' => theme('token_tree', 'all'),
  );

  return $form;
}

/**
 * Process token_actions_message_action form submissions.
 *
 * @see token_actions_message_action()
 * @see token_actions_message_action_form()
 */
function token_actions_message_action_submit($form, $form_state) {
  return array('message' => $form_state['values']['message']);
}

/**
 * Action callback to redirect the user to a tokenized URL.
 *
 * @see token_actions_goto_action_form()
 * @see token_actions_goto_action_submit()
 */
function token_actions_goto_action($object, $context) {
  token_normalize_context($context);
  drupal_goto(token_replace_multiple($context['url'], $context));
}

/**
 * Form builder; Prepare a form for a tokenized redirect action.
 *
 * @see token_actions_goto_action()
 * @see token_actions_goto_action_submit()
 */
function token_actions_goto_action_form($context) {
  $context += array('url' => '');

  $form['url'] = array(
    '#type' => 'textfield',
    '#title' => t('URL'),
    '#description' => t('The URL to which the user should be redirected. This can be an internal URL like node/1234 or an external URL like http://drupal.org.'),
    '#default_value' => $context['url'],
    '#required' => TRUE,
    '#element_validate' => array('token_element_validate'),
    '#token_types' => array('all'),
  );

  $form['help'] = array(
    '#type' => 'fieldset',
    '#collapsible' => TRUE,
    '#collapsed' => TRUE,
    '#title' => t('Placeholder tokens'),
    '#description' => t("The following placeholder tokens can be used in the URL path. Some tokens may not be available, depending on the context in which the action is triggered."),
  );
  $form['help']['tokens'] = array(
    '#value' => theme('token_tree', 'all'),
  );

  return $form;
}

/**
 * Process token_actions_goto_action form submissions.
 *
 * @see token_actions_goto_action()
 * @see token_actions_goto_action_form()
 */
function token_actions_goto_action_submit($form, $form_state) {
  return array('url' => $form_state['values']['url']);
}

/**
 * Normalize an action context for use with token_replace_multiple().
 */
function token_normalize_context(&$context) {
  $context['global'] = NULL;

  if (empty($context['user']) && !empty($context['node'])) {
    $context['user'] = user_load(array('uid' => $context['node']->uid));
  }
  if (empty($context['node']) && !empty($context['comment']) && !empty($context['comment']->nid)) {
    $context['node'] = node_load($context['comment']->nid);
  }
  if (empty($context['user']) && !empty($context['account'])) {
    $context['user'] = $context['account'];
  }
}