Overview
--------
Webform supports theming similar to the Flexinode or Views modules. Any webform
may be themed on the server side, though doing so may require a reasonable
amount of knowledge about the Drupal Forms API. More information about the Forms
API may be found at http://api.drupal.org/api/file/developer/topics/forms_api.html

Theme submission emails
-----------------------
The default emails sent by webform are fairly basic. If you like, you may
customize the display of emails sent by each individual webform. This tutorial
assumes use of the phptemplate engine.

- Open your template.php file located in your theme's directory.
- Add the following lines of php code:

function phptemplate_webform_mail_message_[node id here]($form_values, $node, $sid, $cid) {
  return _phptemplate_callback('webform-mail-[node id here]', array('form_values' => $form_values, 'node' => $node, 'sid' => $sid, 'cid' => $cid));
}

- Create a new file in your theme's directory named
  "webform-mail-[node id here].tpl.php", once again replacing [node id here]
  with the node ID of the webform.
  
- Open up your new file and customize the webform email. Here's a simple template
  to get you started:
  
  <?php /* Begin sample webform mail message file */ ?>
  
  Company X Official Website Submission
  
  Message was submitted <?php echo format_date(time(), 'small') ?>
  
  From the IP address <?php echo $_SERVER['REMOTE_ADDR']; ?>
  
  The user's favorite color is <?php echo $form_values['submitted_tree']['favorite_color'] ?>
  
  The user's problem is below:
  <?php echo $form_values['submitted_tree']['problem'] ?>
  
  <?php /* End sample webform mail message file */ ?>

- To get a better idea of what variables are available to you, you can include
  the print_r function in your email. Simply include the line:
  
  <?php print_r($form_values) ?>
  
  to get a listing of all the available fields you can use in your mail.
  
- An Important Note for Webform Themers: When webform added support for fieldsets
  (i.e. nested fields), it became necessary to increase the complexity of themed
  emails. Previously, the $form_values variable only sent the values of the form in
  a flat array. Now, $form_values contains two arrays of information:
  
  $form_values['submitted'] => An array of fields and their submitted values (identical to the previous value of $form_values)
  $form_values['submitted_tree'] => An array of fields and their values structured in a recursive array

- Advanced Webform e-mail Theming: Theming the e-mail headers may also be done
  by overriding the theme_webform_mail_headers() function from webform.module.
  Just copy the code out of webform.module and change as necessary in your
  template.php file. This allows you to customize the e-mail headers.


Theme the confirmation page
---------------------------

After a user submits a webform, they are directed to a page that contains the
confirmation message set in the webform node settings (assuming the form doesn't
direct to a complete URL). These instructions let you customize the format of
the confirmation page of a single node or all webforms on your site.

- Open your template.php file located in your theme's directory.
- Add the following lines of php code:

function phptemplate_webform_confirmation_[node id here]($node, $sid) {
  return _phptemplate_callback('webform-confirmation-[node id here]', array('node' => $node, 'sid' => $sid));
}

- Create a new file in your theme's directory named
  "webform-confirmation-[node id here].tpl.php", once again replacing [node id here]
  with the node ID of the webform.
  
- Open the new file and change it's contents to the your liking. Here's an
  example that inserts some additional HTML around the confirmation message and
  gives links to edit the submission.
  
  <?php /* Begin sample webform confirmation page */ ?>
  
  <div class="confirmation-message">
    <?php print check_markup($node->webform['confirmation'], $node->format, FALSE); ?>
  </div>
  
  <ul>
    <li><a href="<?php print url('node/'. $node->nid . '/submission/'. $sid)?>">View your submission</a></li>
    <li><a href="<?php print url('node/'. $node->nid . '/submission/'. $sid .'/edit')?>">Edit your submission</a></li>
  </ul>
  
  <?php /* End sample webform confirmation page */ ?>

- You can make this apply to all webforms by using this function in template.php

function phptemplate_webform_confirmation($node, $sid) {
  return _phptemplate_callback('webform-confirmation', array('node' => $node, 'sid' => $sid));
}

- Note that the [node id here] has simply been removed to make it work with all
  webform nodes.

Theme display of an entire webform
----------------------------------

Theming a webform can be useful for rearranging elements or customizing the
appearance of multiple components at once. This tutorial assumes usage
of the phptemplate engine.

- Open your template.php file located in your theme's directory.
- Add the following lines of php code:

function phptemplate_webform_form_[node id here] ($form) {
  return _phptemplate_callback('webform_form_[node id here]', array('form' => $form));
}

- Replace "[node id here]" with the node ID of the form.

- Create a new file in your theme's directory named
  "webform-form-[node id here].tpl.php", once again replacing [node id here]
  with the node ID of the webform.
  
- Open up your new file and customize the webform however you like. Here's an
  example putting a field with the "email" key inside of another fieldset.
  
<?php
  // Create a new fieldset within the main fieldset
  // Note: All fields MUST stay within the 'submitted' fieldset
  $form['submitted']['newfieldset'] = array(
    '#type' => 'fieldset',
  );
  
  // Move the form field labeled "email" to the new fieldset
  $form['submitted']['newfieldset']['email'] = $form['submitted']['email'];
  unset($form['submitted']['email']);
  print drupal_render($form);
?>

- All webform forms have 2 main fieldsets: "submitted", and "details". Although
  you may move things around as you wish, keep all your components within the
  "submitted" fieldset. Only the "submitted" fieldset is displayed and webform
  depends on the other two to operate properly, so don't mess with them unless
  you have good reason to do so (like you're forwarding your webform to a custom
  PHP or PERL script).


$Id: THEMING.txt,v 1.8.2.4.2.7 2008-09-06 06:07:54 quicksketch Exp $