mailhandler.admin.inc in Mailhandler 6

Same filename and directory in other branches
7 mailhandler.admin.inc
Administrator pages for the Mailhandler module.
Manage module settings form and the Mailhandler Mailboxes management section.
File

mailhandler.admin.inc
View source
<?php

/**
 * @file
 * Administrator pages for the Mailhandler module.
 *
 * Manage module settings form and the Mailhandler Mailboxes management section.
 */

/**
 * Return a form for editing or creating an individual mailbox.
 */
function mailhandler_add_edit_mailbox($form_state, $mailbox = FALSE, $clone = FALSE) {

  // @todo: remove this line when decoupling retrieving. used to get information
  // about authentication methods (where authentication has to be decoupled).
  module_load_include('inc', 'mailhandler', 'mailhandler.retrieve');

  // $mid parameter is expected to be a valid mailbox or NULL. If mid is defined
  // but no mailbox is found for this id, then return a 404, as the only way to
  // reach this situation is by a wrong link.
  if ($mailbox && !isset($mailbox['mid'])) {
    drupal_not_found();
    return;
  }

  // If there is a not finished form submission, get the current form values and
  // populate the form fields.
  if (isset($form_state['mailbox'])) {
    $mailbox = $form_state['mailbox'] + (array) $mailbox;
  }

  // Attach default fields for new created mailboxes.
  $mailbox = $mailbox ? $mailbox : mailhandler_mailbox_defaults();
  $form['mail'] = array(
    '#type' => 'textfield',
    '#title' => t('E-mail address'),
    '#default_value' => $mailbox['mail'],
    '#description' => t('The e-mail address to which users should send their submissions.'),
    '#required' => TRUE,
  );

  // Currently has no known usage in mailhandler module, but other modules (e.g.
  // listhandler) may be making use of this.
  // @todo: verify usage and decide removal or not.
  $form['mailto'] = array(
    '#type' => 'textfield',
    '#title' => t('Second E-mail address'),
    '#default_value' => $mailbox['mailto'],
    '#description' => t('Optional. The e-mail address to which modules should send generated content.'),
  );
  $form['folder'] = array(
    '#type' => 'textfield',
    '#title' => t('Folder'),
    '#default_value' => $mailbox['folder'],
    '#description' => t('Optional. The folder where the mail is stored. If you want this mailbox to read from a local folder, give the full path. Leave domain, port, name, and pass empty below. Remember to set the folder to readable and writable by the webserver.'),
  );
  $form['imap'] = array(
    '#type' => 'select',
    '#title' => t('POP3 or IMAP Mailbox'),
    '#options' => array(
      'POP3',
      'IMAP',
    ),
    '#default_value' => $mailbox['imap'],
    '#description' => t('If you wish to retrieve mail from a POP3 or IMAP mailbox instead of a Folder, select POP3 or IMAP. Also, complete the Mailbox items below.'),
  );
  $form['domain'] = array(
    '#type' => 'textfield',
    '#title' => t('Mailbox domain'),
    '#default_value' => $mailbox['domain'],
    '#description' => t('The domain of the server used to collect mail.'),
  );
  $form['port'] = array(
    '#type' => 'textfield',
    '#title' => t('Mailbox port'),
    '#size' => 5,
    '#maxlength' => 5,
    '#default_value' => $mailbox['port'],
    '#description' => t('The port of the mailbox used to collect mail (usually 110 for POP3, 143 for IMAP).'),
  );
  $form['name'] = array(
    '#type' => 'textfield',
    '#title' => t('Mailbox username'),
    '#default_value' => $mailbox['name'],
    '#description' => t('This username is used while logging into this mailbox during mail retrieval.'),
  );
  $form['pass'] = array(
    '#type' => 'textfield',
    '#title' => t('Mailbox password'),
    '#default_value' => $mailbox['pass'],
    '#description' => t('The password corresponding to the username above. Consider using a non-vital password, since this field is stored without encryption in the database.'),
  );

  // Allow administrators to configure the mailbox with extra IMAP commands (notls, novalidate-cert etc.)
  $form['extraimap'] = array(
    '#type' => 'textfield',
    '#title' => t('Extra commands'),
    '#default_value' => $mailbox['extraimap'],
    '#description' => t('Optional. In some circumstances you need to issue extra commands to connect to your mail server (e.g. "/notls", "/novalidate-cert" etc.). See documentation for <a href="http://php.net/imap_open">imap_open</a>. Begin the string with a "/", separating each subsequent command with another "/".'),
  );
  $form['mime'] = array(
    '#type' => 'select',
    '#title' => t('MIME preference'),
    '#options' => array(
      'TEXT/HTML,TEXT/PLAIN' => 'HTML',
      'TEXT/PLAIN,TEXT/HTML' => t('Plain text'),
    ),
    '#default_value' => $mailbox['mime'],
    '#description' => t('When a user sends an e-mail containing both HTML and plain text parts, use this part as the node body.'),
  );
  $form['security'] = array(
    '#type' => 'radios',
    '#title' => t('Security'),
    '#options' => array(
      t('Disabled'),
      t('Require password'),
    ),
    '#default_value' => $mailbox['security'],
    '#description' => t('Disable security if your site does not require a password in the Commands section of incoming e-mails. Note: Security=Enabled and MIME preference=HTML is an unsupported combination.'),
  );
  $form['replies'] = array(
    '#type' => 'radios',
    '#description' => t('Send helpful replies to all unsuccessful e-mail submissions. Consider disabling when a listserv posts to this mailbox.'),
    '#title' => t('Send error replies'),
    '#options' => array(
      t('Disabled'),
      t('Enabled'),
    ),
    '#default_value' => $mailbox['replies'],
  );
  $form['fromheader'] = array(
    '#type' => 'textfield',
    '#title' => t('From header'),
    '#default_value' => $mailbox['fromheader'],
    '#description' => t('Use this e-mail header to determine the author of the resulting node. Admins usually leave this field blank (thus using the <strong>From</strong> header), but <strong>Sender</strong> is also useful when working with listservs.'),
  );
  $form['commands'] = array(
    '#type' => 'textarea',
    '#title' => t('Default commands'),
    '#default_value' => $mailbox['commands'],
    '#description' => t('A set of commands which are added to each message. One command per line. See <a href="@link">Commands</a>.', array(
      '@link' => url('admin/help/mailhandler/#commands'),
    )),
  );
  $form['sigseparator'] = array(
    '#type' => 'textfield',
    '#title' => t('Signature separator'),
    '#default_value' => $mailbox['sigseparator'],
    '#description' => t('All text after this string will be discarded. A typical value is <strong>"-- "</strong> that is two dashes followed by a blank in an otherwise empty line. Leave blank to include signature text in nodes.'),
  );
  $form['delete_after_read'] = array(
    '#type' => 'checkbox',
    '#title' => t('Delete messages after they are processed?'),
    '#default_value' => $mailbox['delete_after_read'],
    '#description' => t('Uncheck this box to leave read messages in the mailbox. They will not be processed again unless they become marked as unread.  If you selected "POP3" as your mailbox type, you must check this box.'),
  );
  $form['enabled'] = array(
    '#type' => 'radios',
    '#title' => t('Cron processing'),
    '#options' => array(
      t('Disabled'),
      t('Enabled'),
    ),
    '#default_value' => $mailbox['enabled'],
    '#description' => t('Select disable to temporarily stop cron processing for this mailbox.'),
  );

  // Allow administrators to select the format of saved nodes/comments
  $form['format'] = filter_form($mailbox['format']);
  $options = array();
  $descriptions = '';
  $options[0] = t('Choose method');
  $methods = mailhandler_mailhandler_authenticate('info');
  foreach ($methods as $method) {
    foreach ($method as $name => $info) {
      $options[$name] = t($info['title']);

      // TODO: theme function
      $descriptions .= t($info['title']) . ": " . t($info['description']) . "\n";
    }
  }
  $form['authentication'] = array(
    '#type' => 'select',
    '#title' => t('Message authentication method'),
    '#options' => $options,
    '#description' => t('Following is the name and description of each available authentication method') . "\n\n" . $descriptions,
    '#default_value' => $mailbox['authentication'],
  );
  $form['actions'] = array(
    '#prefix' => '<p><div class="confirmation container-inline">',
    '#suffix' => '</div></p>',
  );
  $form['actions']['submit'] = array(
    '#type' => 'submit',
    '#value' => t('Save mailbox'),
  );
  $form['actions']['test'] = array(
    '#type' => 'submit',
    '#value' => t('Test connection'),
    '#submit' => array(
      'mailhandler_mailbox_test_submit',
    ),
  );

  // Save mailbox Id for edited mailboxes only. Also show Delete button.
  if (isset($mailbox['mid']) && !$clone) {
    $form['mid'] = array(
      '#type' => 'value',
      '#value' => $mailbox['mid'],
    );
    $form['actions']['delete'] = array(
      '#type' => 'submit',
      '#value' => t('Delete mailbox'),
      '#submit' => array(
        'mailhandler_delete_mailbox_submit',
      ),
      '#validate' => array(),
    );
  }
  $form['actions']['cancel'] = array(
    '#value' => l(t('Cancel'), 'admin/content/mailhandler'),
  );
  return $form;
}

/**
 * Validation hook for mailhandler_add_edit_mailbox() form.
 */
function mailhandler_add_edit_mailbox_validate($form, &$form_state) {
  $mailbox = $form_state['values'];
  mailhandler_mailbox_validate($mailbox, $form, $form_state);
}

/**
 * Submit handler for mailhandler_add_edit_mailbox() form.
 *
 * Add or update a mailbox.
 */
function mailhandler_add_edit_mailbox_submit($form, &$form_state) {
  $mailbox = $form_state['values'];
  if (isset($mailbox['mid'])) {
    drupal_set_message(t('Mailbox %mailbox updated.', array(
      '%mailbox' => $mailbox['mail'],
    )));
  }
  else {
    drupal_set_message(t('Mailbox %mailbox added.', array(
      '%mailbox' => $mailbox['mail'],
    )));
  }
  $form_state['redirect'] = 'admin/content/mailhandler';
  mailhandler_mailbox_save($mailbox);
}

/**
 * Submit handler for Test mailbox button on mailhandler_add_edit_mailbox form.
 *
 * This submit handler will not save any data, but the submitted values must be
 * available for the next form building operation.
 */
function mailhandler_mailbox_test_submit($form, &$form_state) {
  $mailbox = $form_state['values'];
  mailhandler_mailbox_test($mailbox, $form, $form_state);
  if (!($errors = form_get_errors())) {
    drupal_set_message('Mailhandler was able to connect to the mailbox.');
  }

  // Do not save the data, but keep the form values updated.
  $form_state['mailbox'] = $mailbox;
  $form_state['rebuild'] = TRUE;
}

/**
 * Submit handler for Delete button on mailhandler_add_edit_mailbox form.
 */
function mailhandler_delete_mailbox_submit($form, &$form_state) {
  $form_state['redirect'] = array(
    'admin/content/mailhandler/delete/' . $form_state['values']['mid'],
  );
}

/**
 * Display a confirmation form before deleting a Mailbox.
 */
function mailhandler_admin_delete_confirm($form_state, $mailbox = NULL) {
  $form = array();

  // $mailbox parameter is expected to be a valid mailbox or NULL.
  if (!$mailbox) {
    drupal_not_found();
    return;
  }

  // Save the mailbox for the confirm_form.
  $form['mailbox'] = array(
    '#type' => 'value',
    '#value' => $mailbox,
  );

  // Build a confirmation form to delete this entry.
  return confirm_form($form, t('Do you wish to delete mailbox %mailbox?', array(
    '%mailbox' => $mailbox['mail'],
  )), 'admin/content/mailhandler', t('This action cannot be undone.'), t('Delete'), t('Cancel'));
}

/**
 * Submit hook for mailhandler_admin_delete_confirm form.
 *
 * This function assumes that $form_state['values']['mailbox'] is present and it
 * is a valid mailbox (verified at mailhandler_admin_delete_confirm_form).
 */
function mailhandler_admin_delete_confirm_submit($form, &$form_state) {
  $mailbox = $form_state['values']['mailbox'];
  drupal_set_message(t('Mailbox %mailbox deleted.', array(
    '%mailbox' => $mailbox['mail'],
  )));
  $form_state['redirect'] = 'admin/content/mailhandler';
  mailhandler_mailbox_delete($mailbox);
}

/**
 * Displays a list of mailboxes with operations.
 *
 * @return
 * Mailboxes list rendered content.
 */
function mailhandler_list_mailboxes() {
  $rows = array();

  // Define a table header.
  $header = array(
    t('Mailbox'),
    t('Folder'),
    array(
      'data' => t('Operations'),
      'colspan' => 4,
    ),
  );

  // Show all the emails configured.
  foreach (mailhandler_mailbox_load_multiple() as $mid => $mailbox) {
    $rows[] = array(
      '<a href="mailto:' . $mailbox->mail . '">' . $mailbox->mail . '</a>',
      $mailbox->folder ? check_plain($mailbox->folder) : '',
      l(t('Retrieve'), 'admin/content/mailhandler/retrieve/' . $mid, array(
        'attributes' => array(
          'title' => t('Retrieve and process pending e-mails in this mailbox.'),
        ),
      )),
      l(t('Edit'), 'admin/content/mailhandler/edit/' . $mid, array(
        'attributes' => array(
          'title' => t('Edit this mailbox configuration.'),
        ),
      )),
      l(t('Clone'), 'admin/content/mailhandler/clone/' . $mid, array(
        'attributes' => array(
          'title' => t('Add a new mailbox, using this mailbox configuration as a template.'),
        ),
      )),
      l(t('Delete'), 'admin/content/mailhandler/delete/' . $mid, array(
        'attributes' => array(
          'title' => t('Delete this mailbox.'),
        ),
      )),
    );
  }

  // Show the list of mailboxes as a themed table.
  return theme('table', $header, count($rows) ? $rows : array(
    array(
      array(
        'data' => '<em>' . t('No mailboxes have been defined.') . '</em>',
        'colspan' => 4,
      ),
    ),
  ));
}

/**
 * Return the settings page for mailhandler
 */
function mailhandler_admin_settings() {
  $form['mailhandler_default_type'] = array(
    '#type' => 'radios',
    '#title' => t('Default content type'),
    '#description' => t('If an incoming message does not specify a particular content type, then use this type as a default.'),
    '#options' => node_get_types('names'),
    '#default_value' => mailhandler_default_type(),
  );
  $form['mailhandler_max_retrieval'] = array(
    '#type' => 'textfield',
    '#title' => t('Cron maximum message retrieval'),
    '#description' => t('To prevent timeout errors from large mailboxes you can limit the maximum number of messages that will be processed during each cron run. This is a global setting and applies to all mailboxes. A value of zero means that no limit will be applied. Some trial and error may be needed to find the optimum setting.'),
    '#default_value' => variable_get('mailhandler_max_retrieval', 0),
  );
  $form['mailhandler_default_encoding'] = array(
    '#type' => 'textfield',
    '#title' => t('Default character encoding'),
    '#description' => t('The default character encoding to use when an incoming message does not define an encoding.'),
    '#default_value' => variable_get('mailhandler_default_encoding', 'UTF-8'),
  );
  $form['mailhandler_watchdog_level'] = array(
    '#title' => t('Recorded events severity'),
    '#type' => 'select',
    '#options' => watchdog_severity_levels(),
    '#description' => t('Mailhandler will record messages to the selected facility for levels including Emergency up to the selected value here. For more information about the meaning of each category visit !link.', array(
      '!link' => l('severity levels defined in RFC 3164, section 4.1.1', 'http://www.faqs.org/rfcs/rfc3164.html'),
    )),
    '#default_value' => variable_get('mailhandler_watchdog_level', WATCHDOG_INFO),
  );
  $form['#validate'][] = 'mailhandler_admin_settings_validate';
  return system_settings_form($form);
}

/**
 * Validation for mailhandler settings page
 */
function mailhandler_admin_settings_validate($form, &$form_state) {
  if (empty($form_state['values']['mailhandler_max_retrieval'])) {
    $form_state['values']['mailhandler_max_retrieval'] = 0;
  }
  if (!is_numeric($form_state['values']['mailhandler_max_retrieval']) || $form_state['values']['mailhandler_max_retrieval'] < 0 || $form_state['values']['mailhandler_max_retrieval'] != intval($form_state['values']['mailhandler_max_retrieval'])) {
    form_set_error('mailhandler_max_retrieval', t('The value should a positive integer, or zero.'));
  }
}
Functions

Name	Description
mailhandler_add_edit_mailbox	Return a form for editing or creating an individual mailbox.
mailhandler_add_edit_mailbox_submit	Submit handler for mailhandler_add_edit_mailbox() form.
mailhandler_add_edit_mailbox_validate	Validation hook for mailhandler_add_edit_mailbox() form.
mailhandler_admin_delete_confirm	Display a confirmation form before deleting a Mailbox.
mailhandler_admin_delete_confirm_submit	Submit hook for mailhandler_admin_delete_confirm form.
mailhandler_admin_settings	Return the settings page for mailhandler
mailhandler_admin_settings_validate	Validation for mailhandler settings page
mailhandler_delete_mailbox_submit	Submit handler for Delete button on mailhandler_add_edit_mailbox form.
mailhandler_list_mailboxes	Displays a list of mailboxes with operations.
mailhandler_mailbox_test_submit	Submit handler for Test mailbox button on mailhandler_add_edit_mailbox form.
You are here

mailhandler.admin.inc in Mailhandler 6

File

Functions

API Navigation
