function support_client_form in Support Ticketing System 7

Administratively add/update a client.

File

./support.admin.inc, line 18

support.admin.inc

Code

function support_client_form($form, &$form_state, $client, $op = 'edit') {

  // During initial form build, add the entity to the form state for use
  // during form building and processing. During a rebuild, use what is in the
  // form state.
  $client = $form_state['support_client'];

  // @@@ These defaults should go in a custom entity class...
  $defaults = array(
    'name' => '',
    'path' => '',
    'status' => 1,
    'parent' => 0,
    'integrate_email' => 0,
    // correct default?
    'server_name' => '',
    'server_username' => '',
    'server_password' => '',
    'mailbox' => 'INBOX',
    'mailfrom' => '',
    'port' => '',
    'protocol' => 0,
    'extra' => '/novalidate-cert',
    'thread_subject' => 0,
    'domains' => '*',
    'user_creation' => 0,
    'autosubscribe' => '',
    'autoassign' => '',
    'notes' => '',
  );
  foreach ($defaults as $key => $value) {
    if (!isset($client->{$key})) {
      $client->{$key} = $value;
    }
  }
  $form_state['support_client'] = $client;

  // Only enable if we end up needing this due to an api limitation...
  // $form['#client'] = $form_state['client'];
  $form['name'] = array(
    '#title' => t('Client name'),
    '#type' => 'textfield',
    '#required' => TRUE,
    '#default_value' => $client->name,
    '#description' => t('A unique name to be displayed throughout the website and in emails.'),
  );

  // NOTE: This is actually 'path' but calling it that here confuses pathauto. We fix it up in the submit function.
  $form['client_path'] = array(
    '#title' => t('Machine-readable name'),
    '#type' => 'machine_name',
    '#required' => TRUE,
    '#default_value' => $client->path,
    '#size' => 15,
    '#description' => t('The machine-readable name is used to build a unqiue URI for accessing client tickets. It must contain only letters, numbers, and underscores.'),
    '#machine_name' => array(
      'exists' => '_support_client_path_exists',
      'label' => t('Path'),
      'standalone' => TRUE,
    ),
  );
  $form['status'] = array(
    '#title' => t('Status'),
    '#type' => 'radios',
    '#options' => array(
      1 => t('Enabled'),
      2 => t('Disabled'),
    ),
    '#default_value' => $client->status,
    '#description' => t('Tickets will only be displayed for enabled clients.'),
  );
  $query = new EntityFieldQuery();
  $query
    ->entityCondition('entity_type', 'support_client')
    ->entityCondition('status', 1)
    ->entityCondition('parent', 0);

  // Don't let us be our own parent.
  if (!empty($client->clid)) {
    $query
      ->entityCondition('entity_id', $client->clid, '!=');
  }
  $result = $query
    ->execute();
  $clients = array(
    '0' => t('<no parent>'),
  );
  if (!empty($result['support_client'])) {
    $entities = entity_load('support_client', array_keys($result['support_client']));
    foreach ($entities as $key => $entity) {
      $clients[$entity->clid] = $entity->name;
    }
  }
  $form['parent'] = array(
    '#title' => t('Parent'),
    '#type' => 'select',
    '#options' => $clients,
    '#default_value' => $client->parent,
    '#description' => t('Optionally nest a client under another client.'),
  );
  $form['mail'] = array(
    '#title' => t('Inbound email integration'),
    '#type' => 'fieldset',
    '#collapsible' => TRUE,
    '#collapsed' => !$client->integrate_email,
  );
  $form['mail']['integrate_email'] = array(
    '#title' => t('Integrate inbound email'),
    '#type' => 'checkbox',
    '#default_value' => $client->integrate_email,
    '#description' => t('Check this box if you would like to fully integrate this client with an email server.  This will allow users to create and update tickets by email, but it requires a more complex configuration as you need to create a unique mailbox for each integrated client.  If you do not check this box, email notifications will still be mailed out as tickets are created and updated, but replies to these tickets will be ignored.') . ' <em>' . t('Inbound email integration requires that your version of PHP was !compiled.', array(
      '!compiled' => l(t('compiled with the IMAP extension'), 'http://php.net/imap'),
    )) . '</em>',
  );
  $form['mail']['server_name'] = array(
    '#title' => t('Server name'),
    '#type' => 'textfield',
    '#description' => t('Hostname or IP address.'),
    '#default_value' => $client->server_name,
    '#description' => t("The hostname or IP address of the mail server where your client's dedicated email address is hosted.  For example, client %foo may receive email at %email, and so the server name may be %hostname.  The server name may also be an IP address, such as %ip.", array(
      '%foo' => 'foo',
      '%email' => 'foo@support.sample.com',
      '%hostname' => 'support.sample.com',
      '%ip' => '192.168.1.1',
    )),
  );
  $form['mail']['server_username'] = array(
    '#title' => t('Server username'),
    '#type' => 'textfield',
    '#default_value' => $client->server_username,
    '#description' => t("The client's email username.  If a client receives email at %email, the server username is often simply %user.  The support module uses this username to log into the mail server to download messages.", array(
      '%email' => 'foo@support.sample.com',
      '%user' => 'foo',
    )),
  );
  $form['mail']['server_password'] = array(
    '#title' => t('Server password'),
    '#type' => 'textfield',
    '#default_value' => $client->server_password,
    '#description' => t("The client's email password.  The support module uses this password to log into the mail server to download messages. %notice", array(
      '%notice' => t('Note: this is not a password you request from your client.  This is a password you configure on your mail server for managing support tickets for a client.'),
    )),
  );
  $form['mail']['mailbox'] = array(
    '#title' => t('Mailbox'),
    '#type' => 'textfield',
    '#default_value' => $client->mailbox,
    '#description' => t("The mailbox path on your mail server.  You generally do not need to modify this setting."),
  );
  $form['mail']['mailfrom'] = array(
    '#title' => t('From address'),
    '#type' => 'textfield',
    '#default_value' => $client->mailfrom,
    '#description' => t('The email address support should use when sending notification emails.  This must be the same client-specific email address users will send messages to when creating and updating tickets via email.  This will often be comprised of your server username and your server name, such as %email.', array(
      '%email' => 'foo@support.sample.com',
    )),
  );
  $form['mail']['port'] = array(
    '#title' => t('Port'),
    '#type' => 'textfield',
    '#default_value' => $client->port,
    '#description' => t('Specify the TCP port to connect to when downloading email messages.  If using pop3, this port is normally 110.  If using secure pop3, this port is normally 995.  If using imap, this port is normally 143.  If using secure imap this port is normally 993.'),
  );
  $form['mail']['protocol'] = array(
    '#type' => 'radios',
    '#title' => t('Protocol'),
    '#default_value' => 0,
    '#options' => array(
      'pop3',
      'secure pop3',
      'imap',
      'secure imap',
      'local file',
    ),
    '#description' => t('Select the protocol used to obtain messages from your mail server.'),
    '#default_value' => $client->protocol,
  );
  $form['mail']['extra'] = array(
    '#title' => t('Optional extra flags'),
    '#type' => 'textfield',
    '#default_value' => $client->extra,
    '#description' => t('The %pop3, %imap and %ssl flags will be automatically set for you depending on your configuration above.  Additional flags can be manually specified here.  If you are having trouble downloading messages, you may need to change these extra flags as !defined.  These flags are ignored when using the %local protocol.', array(
      '!defined' => l(t('defined here'), 'http://php.net/imap_open#function.imap-open.parameters'),
      '%local' => t('local file'),
      '%pop3' => t('/pop3'),
      '%imap' => t('/imap'),
      '%ssl' => t('/ssl'),
    )),
  );
  $form['mail']['thread_subject'] = array(
    '#type' => 'select',
    '#title' => t('Thread emails using subject'),
    '#options' => array(
      0 => 'Use global setting',
      1 => 'Disabled',
      2 => 'Match against new tickets',
      3 => 'Match against open tickets',
      4 => 'Match against all tickets',
    ),
    '#description' => t('When enabled, the entire message subject will be used to match replies with the original tickets.  By default the !settings configuration will be used, however, you can override this global configuration here.', array(
      '!settings' => l(t('general support settings'), 'admin/support/settings'),
    )),
    '#default_value' => $client->thread_subject,
  );
  $form['mail']['domains'] = array(
    '#type' => 'textfield',
    '#title' => t('Valid email domains'),
    '#default_value' => $client->domains,
    '#description' => t('Enter one or more comma-seperated domains which are allowed to automatically generate new tickets.  If you enter "*" tickets will be allowed from all domains.'),
  );
  $form['mail']['user_creation'] = array(
    '#type' => 'select',
    '#title' => t('Automatic creation of user'),
    '#options' => array(
      'Use global setting',
      'Enable',
      'Disable',
    ),
    '#description' => t('You can override the global setting for autocreating users by selecting an option in this list.  If enabled, new user accounts will be automatically created if emails are received from unnknown email addresses.  If disabled, notification emails will be sent when emails are discarded notifying the sender that they have to register to be able to create or update support tickets via email.'),
    '#default_value' => $client->user_creation,
  );
  $id = isset($client->clid) ? $client->clid : 0;
  $path = 'support/autocomplete/autosubscribe/' . $id;
  $form['autosubscribe'] = array(
    '#type' => 'textfield',
    '#title' => t('Auto-subscribe'),
    '#autocomplete_path' => $path,
    '#maxlength' => 2048,
    '#default_value' => $client->autosubscribe,
    '#description' => t('Enter one or more comma-seperated usernames to auto-subscribe to !client issues.  These users will receive email notifications for all new tickets and ticket updates for this client.', array(
      '!client' => isset($client->name) ? $client->name : 'client',
    )),
  );
  $form['autoassign'] = array(
    '#type' => 'textfield',
    '#title' => t('Auto-assign'),
    '#autocomplete_path' => 'support/autocomplete/assigned/' . $id,
    '#default_value' => $client->autoassign,
    '#description' => t('Optionally enter a username to auto-assign all new tickets for this client to. If left blank, new tickets will be assigned based on your !settings. Enter %nobody to cause new tickets for this client to be assigned to nobody. Enter %creator to cause new tickets for this client to be assigned to the person creating the ticket.', array(
      '!settings' => l(t('general support settings'), 'admin/support/settings'),
      '%nobody' => '<nobody>',
      '%creator' => '<creator>',
    )),
  );
  $form['notes'] = array(
    '#title' => t('Notes'),
    '#type' => 'textarea',
    '#default_value' => $client->notes,
    '#description' => t('Notes are only displayed on this page when editing clients.  They are optional and are provided for administrative purposes.'),
  );
  if (isset($client->clid)) {
    $form['clid'] = array(
      '#type' => 'hidden',
      '#value' => $client->clid,
    );
  }
  $form['actions'] = array(
    '#type' => 'actions',
  );
  $form['actions']['submit'] = array(
    '#type' => 'submit',
    '#value' => t('Save'),
    '#weight' => 40,
  );
  field_attach_form('support_client', $client, $form, $form_state);
  return $form;
}